@tellegen/svelte 0.4.3 → 0.4.4

package/README.md

@@ -39,6 +39,7 @@ remain in the browser on this path.
 `TellegenViewer` accepts:
 
 - `apiBase`, default `/api`
+- `acOpfWasmUrl`, default `null` (optional experimental AC OPF asset)
 - `loadDefaultCases`, default `true`
 - `docsHref`
 - `orgHref`
@@ -68,6 +69,20 @@ 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.
 
+## Experimental AC OPF
+
+A development host can pass `acOpfWasmUrl="/experimental-acopf/tellegen_acopf_wasi.wasm"`
+to `TellegenViewer` or `TellegenProvider`. The asset must be built and served
+separately; the selector enables AC OPF only after a worker probe succeeds.
+See the [local setup and release gates](../../docs/src/acopf-pounce-decision.md#experimental-browser-abi).
+
+Balanced networks and stored canonical AC OPF instances are supported at the
+base operating point. Imported instances retain their objective and constraints.
+Demand/rating editing, LMPs, sensitivities, and saving/exporting the AC OPF case
+are unavailable. Geographic sidecars and layout downloads remain available.
+Without the optional worker, imported AC OPF instances remain viewable but
+cannot be solved. No server solve is substituted for AC OPF.
+
 ## Panel layout
 
 The shell docks Network and Studies on the left, and Solver and Agent on the
@@ -366,6 +381,11 @@ package metadata. The packed smoke test installs the generated tarballs into a
 temporary Svelte consumer and builds it so missing exports, styles, or wasm
 assets fail before publish.
 
+Unmounting `TellegenProvider` (including through `TellegenViewer`) disposes its
+controller and terminates pending AC OPF probes and solves, including background
+cases. Custom hosts that construct a `Controller` directly must call
+`controller.dispose()` when their owning view is destroyed.
+
 ## Citing
 
 If you use this package in published work, please cite the tellegen paper:

package/dist/TellegenMap.svelte

@@ -2,7 +2,7 @@
 	import 'maplibre-gl/dist/maplibre-gl.css';
 	import { tick, untrack } from 'svelte';
 	import type { Layer, PickingInfo } from '@deck.gl/core';
-	import type { IconLayer, PathLayer, ScatterplotLayer } from '@deck.gl/layers';
+	import type { IconLayer, IconLayerProps, PathLayer, ScatterplotLayer } from '@deck.gl/layers';
 	import type { MapLibreOverlay } from '@deck.gl/maplibre';
 	import type { LngLatBoundsLike, Map as MapLibreMap } from 'maplibre-gl';
 	import type { NetworkBranch, NetworkBus } from './api.js';
@@ -22,9 +22,8 @@
 		type SensitivityDomain
 	} from './colors.js';
 	import {
+		applyBasemapTuning,
 		attachBasemapFallback,
-		isOpenFreeMapStyle,
-		openFreeMapEdits,
 		resolveBasemap,
 		type BasemapFallbackReason,
 		type BasemapStyle,
@@ -50,13 +49,18 @@
 		type TransformerMark,
 		multiDiagramNetwork
 	} from './multiconductor.js';
-	import { transformerIcon } from './transformer-icon.js';
+	import {
+		TRANSFORMER_ICON,
+		transformerIconAtlas,
+		transformerIconMapping
+	} from './transformer-icon.js';
 	import { foldMapBounds } from './map-bounds.js';
 	import { getAppState, getController } from './context.svelte.js';
 	import { displayFmt, fmt, rgbaCss } from './format.js';
 	import { getPanelLayout } from './panels.svelte.js';
 	import type { RGBA } from './colors.js';
 	import DiagramCanvas from './components/DiagramCanvas.svelte';
+	import SchematicCanvas from './components/SchematicCanvas.svelte';
 
 	const DEFAULT_CAMERA: CameraSnapshot = { center: [-85, 36], zoom: 4.5, bearing: 0, pitch: 0 };
 
@@ -148,6 +152,24 @@
 	const diagramNetwork = $derived(
 		multiNetwork ?? (displayedNetwork?.coordinate_space === 'diagram' ? displayedNetwork : null)
 	);
+	/** A multiconductor case shown as a schematic replaces both the map and the diagram canvas. */
+	const schematicCase = $derived(
+		!app.studyView && app.activeMulti?.schematic && app.activeMulti.graph ? app.activeMulti : null
+	);
+	// When a case closes its own diagram (Close, Show map), the map continues from the diagram's
+	// geographic view. Switching to another case does not: the map frames the new case instead.
+	let shownSchematic: typeof schematicCase = null;
+	$effect(() => {
+		const now = schematicCase;
+		const before = shownSchematic;
+		shownSchematic = now;
+		untrack(() => {
+			if (before && !now && app.activeMulti === before && !before.schematic && before.lastGeoView) {
+				app.camera = before.lastGeoView;
+				app.cameraHandoff = true;
+			}
+		});
+	});
 	const diagramCaseId = $derived(
 		app.studyView?.caseId ?? diagramMulti?.id ?? diagramCase?.id ?? 'diagram'
 	);
@@ -187,6 +209,11 @@
 	const basemapPrimaryProvider = $derived(basemap.primaryProvider);
 	const basemapFallbackProvider = $derived(basemap.fallbackProvider);
 	const palette = $derived(MAP_PALETTE[theme]);
+	/** The diagram draws on light paper, so its background map is the light basemap whatever the
+	 * map's theme; a host's own style is used as given. */
+	const diagramBasemap = $derived(
+		resolveBasemap({ mapStyle, fallbackMapStyle, theme: 'light', hideBasemapLabels, cartoApiKey })
+	);
 	// Set once a map has existed in this component instance: a rebuild (context
 	// loss or basemap change) restores the camera instead of reframing.
 	let hadMap = false;
@@ -875,23 +902,13 @@
 				// shows every layer again, so both are re-applied on each load.
 				const applyStyleExtras = () => {
 					m.setProjection({ type: untrack(() => projection) });
-					const style = m.getStyle();
-					if (spec.hideLabels) {
-						for (const layer of style.layers) {
-							if (layer.type === 'symbol') m.setLayoutProperty(layer.id, 'visibility', 'none');
-						}
-					}
 					// OpenFreeMap renders as the primary or as the fallback; either
 					// way it is tuned towards CARTO's quieter look.
-					if (!isOpenFreeMapStyle(style)) return;
-					const edits = openFreeMapEdits(
-						style,
+					applyBasemapTuning(
+						m,
+						spec,
 						untrack(() => theme)
 					);
-					for (const edit of edits) {
-						if (edit.kind === 'paint') m.setPaintProperty(edit.layer, edit.property, edit.value);
-						else m.setLayerZoomRange(edit.layer, edit.minzoom, edit.maxzoom);
-					}
 				};
 				m.on('style.load', applyStyleExtras);
 				const detachFallback = attachBasemapFallback(m, spec, {
@@ -1004,12 +1021,16 @@
 					overlay = null;
 				};
 				detachReady = onMapReady?.(m, o);
+				// A view closing onto this map (the diagram, from geographic positions) hands it its
+				// camera to continue from.
+				const handedOff = app.cameraHandoff;
+				app.cameraHandoff = false;
 				// 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);
+				if ((restoreCamera || handedOff) && app.camera) m.jumpTo(app.camera);
 				else if (app.cameraSeq === handledCameraSeq)
 					app.requestFrame(app.activeCaseId ?? app.activeLocalId ?? 'all');
 				if (mapGen > 0) {
@@ -1345,7 +1366,11 @@
 				new IconLayer<TransformerMark>({
 					id: `multi-xfmr-${c.id}`,
 					data: transformerMarks(c.view.edges),
-					getIcon: () => transformerIcon(),
+					// deck.gl makes a texture from any image, canvas included, but types
+					// iconAtlas as a URL or a Texture.
+					iconAtlas: transformerIconAtlas() as unknown as IconLayerProps['iconAtlas'],
+					iconMapping: transformerIconMapping,
+					getIcon: () => TRANSFORMER_ICON,
 					getPosition: (m) => m.position,
 					getAngle: (m) => m.angle,
 					billboard: false,
@@ -1455,7 +1480,7 @@
 	$effect(() => {
 		const seq = app.cameraSeq;
 		const snapshot = app.cameraRequest;
-		if (diagramNetwork || !map || !snapshot || seq === handledCameraSeq) return;
+		if (diagramNetwork || schematicCase || !map || !snapshot || seq === handledCameraSeq) return;
 		handledCameraSeq = seq;
 		handledFrameSeq = app.frameSeq;
 		map.jumpTo(snapshot);
@@ -1467,7 +1492,7 @@
 	// until its cue exists; anything unframeable settles immediately.
 	$effect(() => {
 		const seq = app.frameSeq;
-		if (diagramNetwork || !map || seq === handledFrameSeq) return;
+		if (diagramNetwork || schematicCase || !map || seq === handledFrameSeq) return;
 		const m = map;
 		const target = app.frameTarget;
 		const settle = () => app.settleFrame();
@@ -1497,7 +1522,23 @@
 	});
 </script>
 
-{#if diagramNetwork}
+{#if schematicCase}
+	<!-- One canvas per graph: its layouts, camera and geometry belong to that graph, so another
+	     case, or the same case with coordinates attached, starts afresh. -->
+	{#key schematicCase.graph}
+		<SchematicCanvas
+			mc={schematicCase}
+			onselectbus={(id) => {
+				if (id !== schematicCase.selectedBusId) onmultibusclick(schematicCase.id, id);
+			}}
+			onselectedge={(id) => {
+				if (id !== schematicCase.selectedEdgeId) onmultiedgeclick?.(schematicCase.id, id);
+			}}
+			onclose={() => (schematicCase.schematic = false)}
+			basemap={diagramBasemap}
+		/>
+	{/key}
+{:else if diagramNetwork}
 	<DiagramCanvas
 		network={diagramNetwork}
 		multiconductor={diagramMulti}

package/dist/TellegenProvider.svelte

@@ -21,6 +21,7 @@
 
 	let {
 		apiBase,
+		acOpfWasmUrl,
 		loadDefaultCases,
 		docsHref,
 		orgHref,
@@ -31,14 +32,15 @@
 		children
 	}: Props = $props();
 
-	// 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.
+	// Read once, at mount: `apiBase`, `acOpfWasmUrl` 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,
+				acOpfWasmUrl,
 				loadDefaultCases,
 				docsHref,
 				orgHref,
@@ -56,6 +58,7 @@
 	const app = createAppState();
 	const ctrl = createController(app, {
 		apiBase: config.apiBase,
+		acOpfWasmUrl: config.acOpfWasmUrl ?? undefined,
 		loadDefaultCases: config.loadDefaultCases
 	});
 	// A host that opens its own cases never calls load(), so the shell must not

package/dist/TellegenShell.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { onMount } from 'svelte';
+	import { onMount, untrack } from 'svelte';
 	import AppFooter from './components/AppFooter.svelte';
 	import NotificationCenter from './components/NotificationCenter.svelte';
 	import AppHeader from './components/AppHeader.svelte';
@@ -19,6 +19,14 @@
 
 	let dragDepth = 0;
 
+	// The overview and the diagram read the active case's whole operating point once per solve.
+	$effect(() => {
+		const c = app.activeMulti;
+		void c?.result?.solve_count;
+		void c?.mcFullResult;
+		return untrack(() => ctrl.followOverview(c));
+	});
+
 	// ShellEnvironment drops the affordance when no fine pointer is attached;
 	// forget any drag that was in flight so the next one counts from zero.
 	$effect(() => {
@@ -40,6 +48,7 @@
 	});
 
 	onMount(() => {
+		ctrl.probeAcOpf();
 		// The provider already marked the shell loaded when default cases are
 		// off, and load() itself is gated; this only frames whatever is there.
 		if (config.loadDefaultCases) {

package/dist/TellegenViewer.svelte

@@ -5,6 +5,7 @@
 
 	let {
 		apiBase,
+		acOpfWasmUrl,
 		loadDefaultCases,
 		docsHref,
 		orgHref,
@@ -17,6 +18,7 @@
 
 <TellegenProvider
 	{apiBase}
+	{acOpfWasmUrl}
 	{loadDefaultCases}
 	{docsHref}
 	{orgHref}

package/dist/basemap.d.ts

@@ -189,4 +189,18 @@ export interface BasemapFallbackOptions {
  * again, as they do when `spec.fallback` is `null`. Returns a detach
  * function. */
 export declare function attachBasemapFallback(map: BasemapMapLike, spec: BasemapSpec, handlers?: BasemapFallbackHandlers, options?: BasemapFallbackOptions): () => void;
+/** The parts of a MapLibre map `applyBasemapTuning` touches. */
+export interface TunableMap {
+    getStyle(): StyleSpecification;
+    setLayoutProperty(layer: string, name: string, value: unknown): unknown;
+    setPaintProperty(layer: string, name: string, value: unknown): unknown;
+    setLayerZoomRange(layer: string, minzoom: number, maxzoom: number): unknown;
+}
+/** After a style loads: hide its labels when the spec asks, and tune an OpenFreeMap style (as the
+ * primary or the fallback) towards CARTO's quieter look. `setStyle` undoes both, so run this on
+ * every `style.load`. */
+export declare function applyBasemapTuning(map: TunableMap, spec: BasemapSpec, theme: BasemapTheme): void;
+/** A credit line for a basemap provider, for views that draw their own instead of MapLibre's
+ * attribution control. */
+export declare function basemapCredit(provider: BasemapProvider): string;
 export {};

package/dist/basemap.js

@@ -257,3 +257,30 @@ export function attachBasemapFallback(map, spec, handlers = {}, options = {}) {
         map.off('error', onError);
     };
 }
+/** After a style loads: hide its labels when the spec asks, and tune an OpenFreeMap style (as the
+ * primary or the fallback) towards CARTO's quieter look. `setStyle` undoes both, so run this on
+ * every `style.load`. */
+export function applyBasemapTuning(map, spec, theme) {
+    const style = map.getStyle();
+    if (spec.hideLabels)
+        for (const layer of style.layers)
+            if (layer.type === 'symbol')
+                map.setLayoutProperty(layer.id, 'visibility', 'none');
+    if (!isOpenFreeMapStyle(style))
+        return;
+    for (const edit of openFreeMapEdits(style, theme)) {
+        if (edit.kind === 'paint')
+            map.setPaintProperty(edit.layer, edit.property, edit.value);
+        else
+            map.setLayerZoomRange(edit.layer, edit.minzoom, edit.maxzoom);
+    }
+}
+/** A credit line for a basemap provider, for views that draw their own instead of MapLibre's
+ * attribution control. */
+export function basemapCredit(provider) {
+    return provider === 'carto'
+        ? '© CARTO © OpenStreetMap contributors'
+        : provider === 'openfreemap'
+            ? '© OpenFreeMap © OpenMapTiles © OpenStreetMap contributors'
+            : '© OpenStreetMap contributors';
+}

package/dist/colors.d.ts

@@ -75,7 +75,12 @@ export declare function sensFlatColor(domain: Pick<SensitivityDomain, 'mean'>):
 export declare function previewScaleFor(domain: Pick<SensitivityDomain, 'scale' | 'flat'>, maxAbsStep: number): number | null;
 /** Zero anchored sensitivity domain with a flat column guard. */
 export declare function sensitivityDomain(values: number[]): SensitivityDomain;
-/** Branch color by loading fraction: warm gray, amber past 0.6, red past 0.9. */
+/** Loading, as a fraction of rating, from which a branch needs attention. Both loading scales
+ * share it. An optimal power flow enforces ratings, so its map draws congestion: red from here,
+ * because it cannot exceed 1. A multiconductor power flow does not enforce them, so its overview
+ * warns from here and calls a violation only above 1 (`LOADING_LIMIT` in `diagram/summary.ts`). */
+export declare const LOADING_ATTENTION = 0.9;
+/** Branch color by loading fraction: warm gray, amber past 0.6, red from `LOADING_ATTENTION`. */
 export declare function branchColor(loading: number, inService: boolean): RGBA;
 export declare function branchWidth(loading: number): number;
 /** Bus radius in px; area tracks max(load, gen) so big plants and big loads

package/dist/colors.js

@@ -177,14 +177,21 @@ export function sensitivityDomain(values) {
         flat
     };
 }
-/** Branch color by loading fraction: warm gray, amber past 0.6, red past 0.9. */
+/** Loading, as a fraction of rating, from which a branch needs attention. Both loading scales
+ * share it. An optimal power flow enforces ratings, so its map draws congestion: red from here,
+ * because it cannot exceed 1. A multiconductor power flow does not enforce them, so its overview
+ * warns from here and calls a violation only above 1 (`LOADING_LIMIT` in `diagram/summary.ts`). */
+export const LOADING_ATTENTION = 0.9;
+/** Where the optimal power flow map starts shading a branch towards congestion. */
+const LOADING_ELEVATED = 0.6;
+/** Branch color by loading fraction: warm gray, amber past 0.6, red from `LOADING_ATTENTION`. */
 export function branchColor(loading, inService) {
     if (!inService)
         return [197, 191, 178, 110];
-    if (loading < 0.6)
+    if (loading < LOADING_ELEVATED)
         return [138, 131, 117, 200];
-    if (loading < 0.9)
-        return lerpColor([138, 131, 117, 210], [212, 116, 34, 240], (loading - 0.6) / 0.3);
+    if (loading < LOADING_ATTENTION)
+        return lerpColor([138, 131, 117, 210], [212, 116, 34, 240], (loading - LOADING_ELEVATED) / (LOADING_ATTENTION - LOADING_ELEVATED));
     return [179, 38, 30, 250];
 }
 export function branchWidth(loading) {

package/dist/components/FormulationSelector.svelte

@@ -19,7 +19,7 @@
 			>
 				{#each FORMULATIONS as f (f.id)}
 					{@const unavailable =
-						f.disabled ||
+						(f.disabled && !(f.id === 'acopf' && ctrl.acOpfAvailable && !c.perturbed)) ||
 						('declaredFormulation' in c &&
 							c.declaredFormulation != null &&
 							c.declaredFormulation !== f.id)}

package/dist/components/LocalCaseDetails.svelte

@@ -154,15 +154,22 @@
 	{/if}
 	{@render note?.(lc)}
 	{#if lc.summary && lc.studyInputJson}
+		{@const exportUnavailable = ctrl.caseExportUnavailableReason(lc)}
 		<div class="case-actions">
-			<button class="reset" disabled={busy} onclick={() => saveCase(lc)}>Save case</button>
+			<button
+				class="reset"
+				disabled={busy || !!exportUnavailable}
+				title={exportUnavailable ?? undefined}
+				onclick={() => saveCase(lc)}>Save case</button
+			>
 			{#if lc.formulation === 'dcopf' && lc.solution}
 				<button class="reset" disabled={busy} onclick={() => saveSolution(lc)}>Save solution</button
 				>
 			{/if}
 			<button
 				class="reset"
-				disabled={busy}
+				disabled={busy || !!exportUnavailable}
+				title={exportUnavailable ?? undefined}
 				aria-expanded={exportOpen}
 				aria-controls="case-export-formats"
 				onclick={() => (exportOpen = !exportOpen)}
@@ -175,7 +182,9 @@
 				</button>
 			{/if}
 		</div>
-		{#if exportOpen}
+		{#if exportUnavailable}
+			<p class="unavailable">{exportUnavailable}</p>
+		{:else if exportOpen}
 			<ul class="case-actions" id="case-export-formats" aria-label="Export formats">
 				{#each EXPORT_FORMATS as f (f.token)}
 					<li>
@@ -266,4 +275,10 @@
 	.case-actions .reset {
 		margin-top: 0;
 	}
+
+	.unavailable {
+		margin: 8px 0 0;
+		font-size: 12px;
+		color: var(--text-secondary);
+	}
 </style>

package/dist/components/McResults.svelte

@@ -40,6 +40,17 @@
 	});
 	let busChoice = $state('');
 	let edgeChoice = $state('');
+	/** One entry per equipment id. A multi-winding transformer projects to several graph edges
+	 * that share its id (one per winding pair), so the edges are grouped by id. */
+	const equipmentOptions = $derived.by(() => {
+		const byId = new Map<string, string[]>();
+		for (const edge of graph?.edges ?? []) {
+			const ends = byId.get(edge.id) ?? [];
+			ends.push(`${edge.from} - ${edge.to}`);
+			byId.set(edge.id, ends);
+		}
+		return [...byId].map(([id, ends]) => ({ id, label: `${ends.join(', ')}, ${id}` }));
+	});
 	const busId = $derived(
 		selectedBus ??
 			(graph?.buses.some((b) => b.id === busChoice) ? busChoice : graph?.buses[0]?.id) ??
@@ -127,7 +138,11 @@
 		</div>
 		<div>
 			<dt>Load voltage range</dt>
-			<dd>{summary.min_voltage_pu == null || summary.max_voltage_pu == null ? 'n/a' : `${fixed(summary.min_voltage_pu)}–${fixed(summary.max_voltage_pu)} pu`}</dd>
+			<dd>
+				{summary.min_voltage_pu == null || summary.max_voltage_pu == null
+					? 'n/a'
+					: `${fixed(summary.min_voltage_pu)}–${fixed(summary.max_voltage_pu)} pu`}
+			</dd>
 		</div>
 		<div>
 			<dt>Source P / Q</dt>
@@ -228,8 +243,8 @@
 					selectedEdge = null;
 					portPage = 0;
 				}}
-				><option value="">All equipment</option>{#each graph?.edges ?? [] as edge (edge.id)}<option
-						value={edge.id}>{edge.from} - {edge.to}, {edge.id}</option
+				><option value="">All equipment</option>{#each equipmentOptions as option, i (i)}<option
+						value={option.id}>{option.label}</option
 					>{/each}</select
 			></label
 		>