@tellegen/svelte 0.4.2 → 0.4.4

package/dist/controller.svelte.d.ts

@@ -1,7 +1,7 @@
 import { type TellegenApiClient } from './api.js';
 import type { BranchRatingDeltas, Network, NetworkBus, SensitivityColumn, Solution } from './api.js';
 import { CaseState, LocalCase, MulticonductorCase, type AppState, type DemandRangeMode, type SolvableCase } from './state.svelte.js';
-import { type EngineTransport, type McPfDetail, type McPfDetailQuery, type McPfOptions, type McPfSummary, type McStudySnapshot, type BrowserStudy, type Formulation, type IngestedCase, type PowerIoDiagnostic, type SensTarget } from '@tellegen/engine';
+import { type EngineTransport, type McPfDetail, type McPfDetailQuery, type McPfOptions, type McPfResult, type McPfSummary, type McStudySnapshot, type BrowserStudy, type Formulation, type IngestedCase, type PowerIoDiagnostic, type SensTarget } from '@tellegen/engine';
 /** A parsed geographic sidecar awaiting application: the canonical `.geo.json`
  * layer document from the engine's tolerant reader, its source file name, and
  * the reader's notes on records it could not use. */
@@ -34,6 +34,7 @@ export interface ControllerOptions {
     /** Whether `load()` fetches the bundled cases. Default `true`. With
      * `false`, `load()` only marks the shell loaded and frames the map. */
     loadDefaultCases?: boolean;
+    acOpfWasmUrl?: string;
     mcTransport?: Pick<EngineTransport, 'solveMcModule' | 'applyMcGeo'> & Partial<Pick<EngineTransport, 'solveMcStudy' | 'applyMcStudyGeo' | 'createMcPfSession'>>;
 }
 /** Input to `Controller.openBalancedModule` and `replaceLocalCase`: a
@@ -66,6 +67,12 @@ export declare class Controller {
     abort: AbortController | null;
     sensitivity429Until: number;
     serverComputeOff: boolean;
+    /** The optional EPL-bearing WASI asset is never inferred or bundled. */
+    private readonly acOpfWasmUrl;
+    private acOpfProbeStarted;
+    private readonly acOpfProbeAbort;
+    private readonly acOpfSolves;
+    acOpfAvailable: boolean;
     caseStudies: WeakMap<SolvableCase, {
         study: BrowserStudy;
         studyInputJson: string;
@@ -111,6 +118,9 @@ export declare class Controller {
     /** True when two selection targets name the same bus or branch. */
     sameTarget(a: SensTarget, b: SensTarget): boolean;
     isPerturbed(c: SolvableCase | null): boolean;
+    formulationAvailable(c: SolvableCase, formulation: Formulation): boolean;
+    probeAcOpf: () => void;
+    caseExportUnavailableReason(c: SolvableCase): string | null;
     bumpRevision(c: SolvableCase): void;
     setNearbyRangeAnchor(c: SolvableCase, bus: number, delta?: number): void;
     beginBusSelection(c: SolvableCase, busId: number): {
@@ -131,10 +141,10 @@ export declare class Controller {
     getStudy(c: SolvableCase, studyInputJson: string): Promise<BrowserStudy | null>;
     browserSensitivity(c: SolvableCase, studyInputJson: string, target: SensTarget): Promise<SensitivityColumn | null>;
     /** Release every engine handle this controller holds: each case's browser
-     * Study, including one still being built, and each multiconductor
-     * session, with their pending edits and in-flight requests.
-     * `TellegenProvider` calls it when it unmounts; the controller builds no
-     * Study and keeps no new session afterwards. */
+     * Study, including one still being built, its AC OPF solve, each
+     * multiconductor session, with their pending edits and in-flight requests,
+     * and the AC OPF asset probe. `TellegenProvider` calls it when it unmounts;
+     * the controller builds no Study and keeps no new session afterwards. */
     dispose(): void;
     disposeStudy(c: SolvableCase): void;
     acceptSensitivity(c: SolvableCase, col: SensitivityColumn | null, target: SensTarget | null, sensitivitySeq?: number): void;
@@ -354,6 +364,24 @@ export declare class Controller {
      * operating point, from the live session or the stored full result. Null
      * when the operating point changed before the page arrived. */
     multiResultDetail: (c: MulticonductorCase, query: McPfDetailQuery) => Promise<McPfDetail | null>;
+    /** Above this many buses, reading and indexing the whole operating point takes a noticeable
+     * fraction of a second (evidence/diagram), so the overview is computed on request instead of
+     * after every solve. */
+    static readonly AUTO_OVERVIEW_MAX_BUSES = 25000;
+    private overviewSeq;
+    /** Whether this case computes its overview only on request. */
+    overviewOnRequest: (c: MulticonductorCase) => boolean;
+    /** Read the whole operating point into `c.overviewResult` for the overview and the diagram. The
+     * previous result stays visible until the read lands; a newer read supersedes it. */
+    readOverview: (c: MulticonductorCase) => void;
+    private startOverviewRead;
+    /** Follow the active case's solves: read its operating point once load edits settle, or clear it
+     * for a case that computes the overview on request. Call from an effect that tracks the case's
+     * `result` and `mcFullResult`; the returned function cancels a pending read. */
+    followOverview: (c: MulticonductorCase | null) => (() => void) | undefined;
+    /** The complete operating point for whole-network views: the stored result, or one read from
+     * the live session. Null when there is no result or it changed before the read finished. */
+    multiFullResult: (c: MulticonductorCase) => Promise<McPfResult | null>;
     /** Every terminal's identity, voltage, and injected current, as numeric
      * arrays of interleaved `[re, im]` values. */
     multiTerminalTable: (c: MulticonductorCase) => Promise<{

package/dist/controller.svelte.js

@@ -6,7 +6,7 @@ import { placeSyntheticTopology } from './synthetic-layout.js';
 import { distExtensionFormat, isGeoFileName } from './drop-classify.js';
 import { DropBatchGate, readDropFileBytes, validateDropBatch } from './drop-limits.js';
 import { buildGeographicView, buildDiagramView, placeMultiView } from './multiconductor.js';
-import { browserWasmTransport, applyDisplayGeo, applyGeo, applyLayout, createStudy, extractGeo, FORMULATIONS, formatPowerIoDiagnostic, formatOf, ingestCase, ingestDistCaseBytes, ingestJsonDrop, isDisplayFile, isPermanentEngineFailure, parseDisplay, parseGeo, mcPfResultDetail, summarizeMcPfResult } from '@tellegen/engine';
+import { browserWasmTransport, applyDisplayGeo, applyGeo, applyLayout, createStudy, extractGeo, FORMULATIONS, formatPowerIoDiagnostic, formatOf, ingestCase, ingestDistCaseBytes, ingestJsonDrop, isDisplayFile, isPermanentEngineFailure, parseDisplay, parseGeo, probeAcOpfWorker, solveAcOpfModule, solveResponseToSolution, mcPfResultDetail, summarizeMcPfResult } from '@tellegen/engine';
 import { browserSolveFailure, errorText, extent, formulationLabel, rgbaCss } from './format.js';
 import { DEAD_ZONE_MW } from './slider.js';
 const HIDDEN_DEFAULT_CASES_KEY = 'tellegen.hiddenDefaultCases.v1';
@@ -83,6 +83,12 @@ export class Controller {
     // Latched once any server fallback answers 403: compute is disabled on this
     // deploy, so later fallbacks show the notice instead of firing doomed requests.
     serverComputeOff = false;
+    /** The optional EPL-bearing WASI asset is never inferred or bundled. */
+    acOpfWasmUrl;
+    acOpfProbeStarted = false;
+    acOpfProbeAbort = new AbortController();
+    acOpfSolves = new Map();
+    acOpfAvailable = $state(false);
     // Build-once browser Study per case: the retained PowerIO module is parsed and the model built
     // when the Study is created, so a drag re-solves (commit) and previews without
     // re-parsing. Kept in a WeakMap off the reactive/raw case payloads — the wasm
@@ -131,6 +137,7 @@ export class Controller {
         this.api = options.api ?? createApiClient({ apiBase: options.apiBase });
         this.loadDefaultCases = options.loadDefaultCases ?? true;
         this.mcTransport = options.mcTransport ?? browserWasmTransport;
+        this.acOpfWasmUrl = options.acOpfWasmUrl ?? null;
     }
     // ===== helpers =====
     isBackendCase(c) {
@@ -158,6 +165,31 @@ export class Controller {
     isPerturbed(c) {
         return c?.perturbed ?? false;
     }
+    formulationAvailable(c, formulation) {
+        if (formulation === 'acopf')
+            return this.acOpfAvailable && !c.perturbed;
+        return !FORMULATIONS.find((entry) => entry.id === formulation)?.disabled;
+    }
+    probeAcOpf = () => {
+        if (this.disposed || this.acOpfProbeStarted || !this.acOpfWasmUrl)
+            return;
+        this.acOpfProbeStarted = true;
+        void probeAcOpfWorker(this.acOpfWasmUrl, undefined, this.acOpfProbeAbort.signal).then((available) => {
+            if (this.disposed)
+                return;
+            this.acOpfAvailable = available;
+            // A declared instance can be dropped while the optional asset is probing.
+            const c = this.app.activeLocal;
+            if (available && c?.formulation === 'acopf' && !c.solving) {
+                this.maybeStartLocalSolve(c.id);
+            }
+        });
+    };
+    caseExportUnavailableReason(c) {
+        return c.formulation === 'acopf'
+            ? 'Saving and exporting AC OPF cases is not supported yet.'
+            : null;
+    }
     bumpRevision(c) {
         c.revisionGeneration += 1;
     }
@@ -352,18 +384,24 @@ export class Controller {
         return study ? study.sensitivity(c.id, this.caseDeltas(c), this.caseRatings(c), target) : null;
     }
     /** Release every engine handle this controller holds: each case's browser
-     * Study, including one still being built, and each multiconductor
-     * session, with their pending edits and in-flight requests.
-     * `TellegenProvider` calls it when it unmounts; the controller builds no
-     * Study and keeps no new session afterwards. */
+     * Study, including one still being built, its AC OPF solve, each
+     * multiconductor session, with their pending edits and in-flight requests,
+     * and the AC OPF asset probe. `TellegenProvider` calls it when it unmounts;
+     * the controller builds no Study and keeps no new session afterwards. */
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
         this.abort?.abort();
         this.abort = null;
-        for (const c of [...this.app.cases, ...this.app.localCases])
+        this.acOpfProbeAbort.abort();
+        for (const cancellation of this.acOpfSolves.values())
+            cancellation.abort();
+        this.acOpfSolves.clear();
+        for (const c of [...this.app.cases, ...this.app.localCases]) {
+            c.solveSeq = (c.solveSeq ?? 0) + 1;
             this.disposeStudy(c);
+        }
         for (const c of this.app.multiCases) {
             c.solveAbort?.abort();
             if (c.mcEditTimer !== null)
@@ -375,6 +413,8 @@ export class Controller {
     }
     // Release a case's Study (if any) when the case is removed.
     disposeStudy(c) {
+        this.acOpfSolves.get(c)?.abort();
+        this.acOpfSolves.delete(c);
         const cached = this.caseStudies.get(c);
         if (cached) {
             cached.study.free();
@@ -557,7 +597,9 @@ export class Controller {
     sliderBounds = $derived.by(() => this.demandBounds(this.app.demandRangeMode, this.selectedBusData, this.nearbyRangeCenter));
     sliderMin = $derived(this.sliderBounds.min);
     sliderMax = $derived(this.sliderBounds.max);
-    sliderDisabled = $derived(!this.selectedBusData || isDisplayOnlyElement(this.selectedBusData));
+    sliderDisabled = $derived(this.activeFormulation === 'acopf' ||
+        !this.selectedBusData ||
+        isDisplayOnlyElement(this.selectedBusData));
     committedRating = $derived.by(() => this.activeSolvable && this.app.selectedBranch !== null
         ? (this.caseRatings(this.activeSolvable)[this.app.selectedBranch] ?? 0)
         : 0);
@@ -569,7 +611,7 @@ export class Controller {
     // to perturb.
     ratingBounds = $derived.by(() => {
         const b = this.selectedBranchData;
-        if (!b || isDisplayOnlyElement(b) || b.rate_mw <= 0)
+        if (this.activeFormulation === 'acopf' || !b || isDisplayOnlyElement(b) || b.rate_mw <= 0)
             return { min: 0, max: 0, disabled: true };
         const span = Math.min(50, Math.max(5, 0.2 * b.rate_mw));
         return {
@@ -681,6 +723,7 @@ export class Controller {
         if (this.loading)
             return this.loading;
         this.loading = (async () => {
+            this.probeAcOpf();
             // Learn the deploy's compute gate up front so fallback paths pick honest
             // copy and skip doomed requests (the SSE stream cannot see a 403). On
             // failure assume enabled; the 403 latch in fetchServerColumn still
@@ -842,7 +885,7 @@ export class Controller {
         this.app.activeCaseId = null;
         this.leaveMulti();
         this.app.activeLocalId = c.id;
-        if (c.formulation === 'acpf' && this.app.displayMode === 'price')
+        if ((c.formulation === 'acpf' || c.formulation === 'acopf') && this.app.displayMode === 'price')
             this.app.displayMode = 'voltage';
         this.app.placingLocalId = c.coordsKind === 'synthetic_pending' && !c.diagram ? c.id : null;
         if (c.view || c.diagram || c.substations)
@@ -868,7 +911,7 @@ export class Controller {
         this.app.activeCaseId = null;
         this.leaveMulti();
         this.app.addLocal(c);
-        if (c.formulation === 'acpf' && this.app.displayMode === 'price')
+        if ((c.formulation === 'acpf' || c.formulation === 'acopf') && this.app.displayMode === 'price')
             this.app.displayMode = 'voltage';
         if (c.diagram)
             this.app.placingLocalId = null;
@@ -1049,6 +1092,7 @@ export class Controller {
         copy.iterations = source.iterations;
         copy.solveMs = source.solveMs;
         copy.solveBackend = source.solveBackend;
+        copy.solveDetail = source.solveDetail;
         copy.network = source.network;
         if (source.network) {
             copy.view = {
@@ -1121,7 +1165,8 @@ export class Controller {
             'baseSolution',
             'iterations',
             'solveMs',
-            'solveBackend'
+            'solveBackend',
+            'solveDetail'
         ])
             Object.assign(copy, { [key]: source[key] });
         const captured = this.detachedCaseCaptures.get(source);
@@ -1276,7 +1321,7 @@ export class Controller {
                 if (ac.signal.aborted)
                     return;
             }
-            if (c.formulation === 'acpf')
+            if (c.formulation === 'acpf' || c.formulation === 'acopf')
                 return;
             try {
                 // The column from the browser Study (under the case's formulation). DC OPF
@@ -1412,7 +1457,7 @@ export class Controller {
         this.app.placingLocalId = null;
         const { ac, sensitivitySeq } = this.beginBusSelection(c, busId);
         try {
-            if (c.formulation === 'acpf')
+            if (c.formulation === 'acpf' || c.formulation === 'acopf')
                 return;
             const sensitivity = await this.browserSensitivity(c, c.studyInputJson, {
                 bus: busId
@@ -1471,7 +1516,7 @@ export class Controller {
                 if (ac.signal.aborted)
                     return;
             }
-            if (c.formulation === 'acpf')
+            if (c.formulation === 'acpf' || c.formulation === 'acopf')
                 return;
             const sensitivity = await this.browserSensitivity(c, c.studyInputJson, {
                 branch: branchId
@@ -1535,8 +1580,12 @@ export class Controller {
     // fall back: the server solves at base ratings, so a Study failure there is
     // terminal.
     runSolve = (c, target) => {
-        if (c.formulation === 'acpf')
+        if (this.disposed)
+            return;
+        if (c.formulation === 'acpf' || c.formulation === 'acopf')
             target = null;
+        this.acOpfSolves.get(c)?.abort();
+        this.acOpfSolves.delete(c);
         // Cancel this case's own previous server stream, if any (backend only).
         if (this.isBackendCase(c)) {
             c.closeStream?.();
@@ -1547,11 +1596,12 @@ export class Controller {
         this.app.error = null;
         c.solving = true;
         c.solveBackend = null;
+        c.solveDetail = null;
         c.solveFallbackReason = null;
         c.iterations = [];
         c.solveMs = null;
         this.ensureStudyInputJson(c).then(async (studyInputJson) => {
-            if (seq !== (c.solveSeq ?? 0))
+            if (this.disposed || seq !== (c.solveSeq ?? 0))
                 return;
             if (!studyInputJson) {
                 c.solveFallbackReason ??= 'PowerIO module unavailable';
@@ -1574,6 +1624,45 @@ export class Controller {
                 return;
             }
             const t0 = performance.now();
+            if (c.formulation === 'acopf') {
+                if (!this.acOpfAvailable || !this.acOpfWasmUrl) {
+                    c.solving = false;
+                    this.app.error = `${this.caseName(c)}: the experimental AC OPF worker is unavailable`;
+                    return;
+                }
+                if (c.perturbed) {
+                    c.solving = false;
+                    this.app.error = `${this.caseName(c)}: AC OPF currently solves the canonical base case only; reset demand and rating edits first`;
+                    return;
+                }
+                const cancellation = new AbortController();
+                this.acOpfSolves.set(c, cancellation);
+                c.solveBackend = 'pounce-wasi';
+                try {
+                    const response = await solveAcOpfModule(this.acOpfWasmUrl, studyInputJson, cancellation.signal);
+                    if (seq !== (c.solveSeq ?? 0) || cancellation.signal.aborted)
+                        return;
+                    c.solution = solveResponseToSolution(response);
+                    const diagnostics = response.iterations;
+                    c.solveDetail =
+                        diagnostics && !Array.isArray(diagnostics) && 'nlp_iterations' in diagnostics
+                            ? `${diagnostics.total_nlp_iterations ?? diagnostics.nlp_iterations} NLP iterations${diagnostics.recovered_by ? ' (recovered)' : ''}`
+                            : 'POUNCE WASI';
+                    c.solveMs = Math.round(performance.now() - t0);
+                    this.finishSolve(c, seq, null);
+                }
+                catch (error) {
+                    if (seq !== (c.solveSeq ?? 0) || cancellation.signal.aborted)
+                        return;
+                    c.solving = false;
+                    this.app.error = `${this.caseName(c)}: AC OPF failed in the isolated browser worker: ${errorText(error)}`;
+                }
+                finally {
+                    if (this.acOpfSolves.get(c) === cancellation)
+                        this.acOpfSolves.delete(c);
+                }
+                return;
+            }
             c.solveBackend = 'clarabel-wasm';
             // Build-once Study path: commit the new operating point (no re-parse). The
             // selected nodal value sensitivity column is computed in the same
@@ -1763,12 +1852,12 @@ export class Controller {
             this.fail('This PowerIO instance requires its declared calculation.');
             return;
         }
-        if (FORMULATIONS.find((f) => f.id === next)?.disabled)
+        if (!this.formulationAvailable(c, next))
             return;
         c.formulation = next;
         // Demand does not depend on the calculation, so a demand colouring stays.
         if (this.app.displayMode !== 'demand')
-            this.app.displayMode = next === 'acpf' ? 'voltage' : 'price';
+            this.app.displayMode = next === 'acpf' || next === 'acopf' ? 'voltage' : 'price';
         this.bumpRevision(c);
         // The committed point carries over (same demand), but the model and its solution do
         // not; drop the Study and the cached solutions so they rebuild under `next`.
@@ -1777,6 +1866,7 @@ export class Controller {
         c.solution = null;
         c.iterations = [];
         c.solveMs = null;
+        c.solveDetail = null;
         c.predictedObjective = null;
         this.app.previewPrices = null;
         this.previewObjective = null;
@@ -2299,6 +2389,64 @@ export class Controller {
         const full = c.mcFullResult ?? c.mcSnapshot?.result ?? null;
         return full ? mcPfResultDetail(full, query, summary.solve_count) : null;
     };
+    /** Above this many buses, reading and indexing the whole operating point takes a noticeable
+     * fraction of a second (evidence/diagram), so the overview is computed on request instead of
+     * after every solve. */
+    static AUTO_OVERVIEW_MAX_BUSES = 25_000;
+    overviewSeq = 0;
+    /** Whether this case computes its overview only on request. */
+    overviewOnRequest = (c) => (c.graph?.buses.length ?? 0) > Controller.AUTO_OVERVIEW_MAX_BUSES;
+    /** Read the whole operating point into `c.overviewResult` for the overview and the diagram. The
+     * previous result stays visible until the read lands; a newer read supersedes it. */
+    readOverview = (c) => this.startOverviewRead(c, ++this.overviewSeq);
+    startOverviewRead(c, seq) {
+        c.overviewLoading = true;
+        this.multiFullResult(c).then((full) => {
+            if (seq !== this.overviewSeq)
+                return;
+            if (full)
+                c.overviewResult = full;
+            c.overviewLoading = false;
+        }, () => {
+            if (seq === this.overviewSeq)
+                c.overviewLoading = false;
+        });
+    }
+    /** Follow the active case's solves: read its operating point once load edits settle, or clear it
+     * for a case that computes the overview on request. Call from an effect that tracks the case's
+     * `result` and `mcFullResult`; the returned function cancels a pending read. */
+    followOverview = (c) => {
+        const seq = ++this.overviewSeq;
+        if (!c)
+            return;
+        if (c.result?.solve_count === undefined || this.overviewOnRequest(c)) {
+            c.overviewResult = null;
+            c.overviewLoading = false;
+            return;
+        }
+        c.overviewLoading = true;
+        const timer = setTimeout(() => this.startOverviewRead(c, seq), 300);
+        return () => {
+            clearTimeout(timer);
+            // A read still in flight is superseded by the next one, so this case is no longer loading.
+            c.overviewLoading = false;
+        };
+    };
+    /** The complete operating point for whole-network views: the stored result, or one read from
+     * the live session. Null when there is no result or it changed before the read finished. */
+    multiFullResult = async (c) => {
+        if (!c.result)
+            return null;
+        const stored = c.mcFullResult ?? c.mcSnapshot?.result ?? null;
+        const session = c.mcSession;
+        if (stored || !session)
+            return stored;
+        if (c.mcEditRunning)
+            return null;
+        const solve = c.result.solve_count;
+        const full = await session.result();
+        return session === c.mcSession && c.result?.solve_count === solve ? full : null;
+    };
     /** Every terminal's identity, voltage, and injected current, as numeric
      * arrays of interleaved `[re, im]` values. */
     multiTerminalTable = async (c) => {
@@ -2736,6 +2884,11 @@ export class Controller {
      * save or export captures exactly what is on screen. Null (with an error set) when no
      * PowerIO module or Study is available. */
     syncedStudy = async (c) => {
+        const unavailable = this.caseExportUnavailableReason(c);
+        if (unavailable) {
+            this.app.error = `${this.caseName(c)}: ${unavailable}`;
+            return null;
+        }
         const studyInputJson = await this.ensureStudyInputJson(c);
         if (!studyInputJson) {
             this.app.error = `${this.caseName(c)}: no PowerIO module available to save`;
@@ -2818,7 +2971,7 @@ export class Controller {
     // can't preview (browser fallback path, server-only cases): the map then
     // falls back to the JS sensitivity-times-step preview.
     runPreview = (c, bus, value) => {
-        if (c.formulation === 'acpf')
+        if (c.formulation === 'acpf' || c.formulation === 'acopf')
             return;
         // Fast path: the committed price/demand column (already solved at the committed point),
         // scaled by the demand step, is the same first-order linearization the engine preview
@@ -2933,7 +3086,7 @@ export class Controller {
     // point (preview is replacement-absolute, so the absolute ratings map is built),
     // then scaled by the live step; null when no Study slope is available.
     runRatingPreview = (c, branch, value) => {
-        if (c.formulation === 'acpf')
+        if (c.formulation === 'acpf' || c.formulation === 'acopf')
             return;
         const committedAtBranch = this.caseRatings(c)[branch] ?? 0;
         const step = (Math.abs(value) < DEAD_ZONE_MW ? 0 : value) - committedAtBranch;

package/dist/diagram/basemap.d.ts

@@ -0,0 +1,28 @@
+/** The basemap under geographic positions: the main map's own vector style, drawn by a MapLibre map
+ * kept in step with the schematic camera. Geographic positions are Web Mercator metres (y down)
+ * relative to an origin, so the camera converts exactly. */
+/** Shared with the main map, so both backgrounds look the same. */
+export declare const BASEMAP_STYLE = "https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json";
+export declare const BASEMAP_ATTRIBUTION = "\u00A9 CARTO \u00A9 OpenStreetMap contributors";
+/** Longitude and latitude in degrees of a Web Mercator point in metres, y down. */
+export declare function mercatorToLngLat(x: number, y: number): [number, number];
+/** The MapLibre camera showing what a schematic camera shows: same centre, and a zoom at which
+ * one metre spans the same pixels (MapLibre's world is 512 px wide at zoom 0). */
+export declare function basemapCamera(camera: {
+    target: [number, number, number] | [number, number];
+    zoom: number;
+}, origin: [number, number]): {
+    center: [number, number];
+    zoom: number;
+};
+/** Web Mercator metres (y down) of a longitude and latitude in degrees. */
+export declare function lngLatToMercator(lng: number, lat: number): [number, number];
+/** The schematic camera showing what a MapLibre camera shows (the inverse of
+ * {@link basemapCamera}), for opening the diagram where the map was. */
+export declare function cameraFromMap(map: {
+    center: [number, number];
+    zoom: number;
+}, origin: [number, number]): {
+    target: [number, number, number];
+    zoom: number;
+};

package/dist/diagram/basemap.js

@@ -0,0 +1,39 @@
+/** The basemap under geographic positions: the main map's own vector style, drawn by a MapLibre map
+ * kept in step with the schematic camera. Geographic positions are Web Mercator metres (y down)
+ * relative to an origin, so the camera converts exactly. */
+const R = 6_378_137;
+const WORLD = 2 * Math.PI * R;
+/** Shared with the main map, so both backgrounds look the same. */
+export const BASEMAP_STYLE = 'https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json';
+export const BASEMAP_ATTRIBUTION = '© CARTO © OpenStreetMap contributors';
+/** Longitude and latitude in degrees of a Web Mercator point in metres, y down. */
+export function mercatorToLngLat(x, y) {
+    const lng = ((x / R) * 180) / Math.PI;
+    const lat = ((2 * Math.atan(Math.exp(-y / R)) - Math.PI / 2) * 180) / Math.PI;
+    return [lng, lat];
+}
+/** The MapLibre camera showing what a schematic camera shows: same centre, and a zoom at which
+ * one metre spans the same pixels (MapLibre's world is 512 px wide at zoom 0). */
+export function basemapCamera(camera, origin) {
+    return {
+        center: mercatorToLngLat(camera.target[0] + origin[0], camera.target[1] + origin[1]),
+        zoom: Math.log2((WORLD * 2 ** camera.zoom) / 512)
+    };
+}
+/** Web Mercator metres (y down) of a longitude and latitude in degrees. */
+export function lngLatToMercator(lng, lat) {
+    const clamped = Math.max(-85, Math.min(85, lat));
+    return [
+        (R * lng * Math.PI) / 180,
+        -R * Math.log(Math.tan(Math.PI / 4 + (clamped * Math.PI) / 360))
+    ];
+}
+/** The schematic camera showing what a MapLibre camera shows (the inverse of
+ * {@link basemapCamera}), for opening the diagram where the map was. */
+export function cameraFromMap(map, origin) {
+    const [x, y] = lngLatToMercator(map.center[0], map.center[1]);
+    return {
+        target: [x - origin[0], y - origin[1], 0],
+        zoom: Math.log2((512 * 2 ** map.zoom) / WORLD)
+    };
+}

package/dist/diagram/bus-stacks.d.ts

@@ -0,0 +1,19 @@
+import type { DistGraph } from '@tellegen/engine';
+import type { SchematicGeometry } from './schematic-layout.js';
+/** Buses drawn at exactly the same point (an MV and an LV bus at one pole, say). */
+export interface BusStacks {
+    /** Groups of two or more bus indices, in graph order. */
+    groups: number[][];
+    /** Per bus: its group index, or −1 when it stands alone. */
+    stackOf: Int32Array;
+}
+export declare function busStacks(geometry: SchematicGeometry): BusStacks;
+/** Offsets in drawing units that spread a stack's members on a circle of `radiusPx` screen pixels
+ * (`scale` pixels per unit): two side by side, more around the circle from the top. */
+export declare function spreadOffsets(count: number, scale: number, radiusPx?: number): [number, number][];
+/** `geometry` with the given buses moved by their offsets, and every branch end at a moved bus
+ * moved with it (interior route points stay put, so routes bend from the spread bus back onto
+ * their path). A branch whose two ends share a point (a pole transformer between stacked buses)
+ * takes its first end as `from` and its last as `to`. Returns `geometry` itself when nothing
+ * moves. */
+export declare function displaceBuses(graph: DistGraph, geometry: SchematicGeometry, offsets: Map<number, [number, number]>): SchematicGeometry;

package/dist/diagram/bus-stacks.js

@@ -0,0 +1,99 @@
+export function busStacks(geometry) {
+    const n = geometry.positions.length / 3;
+    const byPoint = new Map();
+    for (let i = 0; i < n; i++) {
+        const key = `${geometry.positions[i * 3]},${geometry.positions[i * 3 + 1]}`;
+        const list = byPoint.get(key);
+        if (list)
+            list.push(i);
+        else
+            byPoint.set(key, [i]);
+    }
+    const groups = [];
+    const stackOf = new Int32Array(n).fill(-1);
+    for (const list of byPoint.values())
+        if (list.length > 1) {
+            for (const i of list)
+                stackOf[i] = groups.length;
+            groups.push(list);
+        }
+    return { groups, stackOf };
+}
+/** Offsets in drawing units that spread a stack's members on a circle of `radiusPx` screen pixels
+ * (`scale` pixels per unit): two side by side, more around the circle from the top. */
+export function spreadOffsets(count, scale, radiusPx = 12) {
+    const r = radiusPx / scale;
+    if (count === 2)
+        return [
+            [-r, 0],
+            [r, 0]
+        ];
+    return Array.from({ length: count }, (_, i) => {
+        const a = -Math.PI / 2 + (2 * Math.PI * i) / count;
+        return [r * Math.cos(a), r * Math.sin(a)];
+    });
+}
+/** `geometry` with the given buses moved by their offsets, and every branch end at a moved bus
+ * moved with it (interior route points stay put, so routes bend from the spread bus back onto
+ * their path). A branch whose two ends share a point (a pole transformer between stacked buses)
+ * takes its first end as `from` and its last as `to`. Returns `geometry` itself when nothing
+ * moves. */
+export function displaceBuses(graph, geometry, offsets) {
+    if (!offsets.size)
+        return geometry;
+    const positions = Float32Array.from(geometry.positions);
+    for (const [i, [dx, dy]] of offsets) {
+        positions[i * 3] += dx;
+        positions[i * 3 + 1] += dy;
+    }
+    const sources = Float32Array.from(geometry.sources);
+    const targets = Float32Array.from(geometry.targets);
+    const index = new Map(graph.buses.map((b, i) => [b.id.toLowerCase(), i]));
+    // First and last segment of each edge.
+    const first = new Map();
+    const last = new Map();
+    for (let s = 0; s < geometry.segmentEdge.length; s++) {
+        const k = geometry.segmentEdge[s];
+        if (!first.has(k))
+            first.set(k, s);
+        last.set(k, s);
+    }
+    const at = (i) => [
+        geometry.positions[i * 3],
+        geometry.positions[i * 3 + 1]
+    ];
+    const near = (x, y, i) => {
+        const [px, py] = at(i);
+        return x === px && y === py;
+    };
+    graph.edges.forEach((e, k) => {
+        const s0 = first.get(k);
+        const s1 = last.get(k);
+        if (s0 === undefined || s1 === undefined)
+            return;
+        const a = index.get(e.from.toLowerCase()) ?? -1;
+        const b = index.get(e.to.toLowerCase()) ?? -1;
+        const sx = geometry.sources[s0 * 3];
+        const sy = geometry.sources[s0 * 3 + 1];
+        const tx = geometry.targets[s1 * 3];
+        const ty = geometry.targets[s1 * 3 + 1];
+        // Which bus each end belongs to: the one drawn there, `from` first when both are.
+        const startBus = a >= 0 && near(sx, sy, a) ? a : b >= 0 && near(sx, sy, b) ? b : -1;
+        const endBus = b >= 0 && near(tx, ty, b) && b !== startBus
+            ? b
+            : a >= 0 && near(tx, ty, a) && a !== startBus
+                ? a
+                : -1;
+        const ds = startBus >= 0 ? offsets.get(startBus) : undefined;
+        const de = endBus >= 0 ? offsets.get(endBus) : undefined;
+        if (ds) {
+            sources[s0 * 3] += ds[0];
+            sources[s0 * 3 + 1] += ds[1];
+        }
+        if (de) {
+            targets[s1 * 3] += de[0];
+            targets[s1 * 3 + 1] += de[1];
+        }
+    });
+    return { ...geometry, positions, sources, targets };
+}

package/dist/diagram/colour-modes.d.ts

@@ -0,0 +1,18 @@
+import { type RGBA } from '../colors.js';
+import type { PairVoltage } from './snapshot.js';
+export type ColourMode = 'none' | 'voltage' | 'voltage-band' | 'loading' | 'loading-heat';
+export declare const COLOUR_MODES: Record<ColourMode, {
+    label: string;
+    continuous: boolean;
+}>;
+/** Threshold and continuous variants of one quantity share issue focus, warnings and presets. */
+export declare function colourFamily(mode: ColourMode): 'voltage' | 'loading' | 'none';
+/** Position in the declared band: −1 at min, 0 mid-band, +1 at max; beyond ±1 is a violation. */
+export declare function bandPosition(p: PairVoltage): number | null;
+/** The pair nearest a limit decides a bus colour, so a violation can never be averaged away. */
+export declare function worstBand(pairs: PairVoltage[]): number | null;
+/** The application's sequential ramp; light loads start part-way up so they stay visible on paper. */
+export declare const loadingColour: (loading: number) => RGBA;
+/** The application's diverging ramp over the declared band, clamped at the limits. */
+export declare const bandColour: (t: number) => RGBA;
+export declare const MISSING_COLOUR: RGBA;