@tellegen/svelte 0.4.3 → 0.4.5

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. */
@@ -20,6 +20,9 @@ type SavedCaseCapture = {
 export declare function isDisplayOnlyElement(element: {
     editable?: boolean;
 } | null | undefined): boolean;
+/** Trigger a browser download of in-memory text. Case files never leave the machine:
+ * a save is a local Blob download. */
+export declare function downloadText(text: string, filename: string, mime: string): void;
 export type { SolvableCase };
 type DemandRangeAnchor = {
     caseId: string;
@@ -34,6 +37,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 +70,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 +121,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 +144,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 +367,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<{
@@ -388,6 +419,10 @@ export declare class Controller {
     caseGeographyLayers(c: LocalCase): Promise<string[]>;
     /** Capture a matching cached result without constructing or solving a model. */
     captureSavedCase(c: SolvableCase): Promise<SavedCaseCapture>;
+    /** Record what PowerIO and the engine said while reading a case file. */
+    private logImport;
+    /** Record a geographic layer's reader findings and placement notes. */
+    private logCoordinates;
     /** Build a local case from a balanced PowerIO ingest payload without activating
      * it yet; co-dropped placement data is applied before the first solve. */
     private localFromBalancedPayload;

package/dist/controller.svelte.js

@@ -3,10 +3,11 @@ import { previewScaleFor, scalarDomain, sensFlatColor, sensitivityDomain } from
 import { caseDeltas as sharedCaseDeltas, caseRatings as sharedCaseRatings, displayMetaFor, displaySeriesFor } from './display.js';
 import { CaseState, LocalCase, MulticonductorCase } from './state.svelte.js';
 import { placeSyntheticTopology } from './synthetic-layout.js';
+import { powerIoEntry, solveEntry } from './log.svelte.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';
@@ -52,7 +53,7 @@ function delayUntilFocusSettles(ms, signal) {
 }
 /** Trigger a browser download of in-memory text. Case files never leave the machine:
  * a save is a local Blob download. */
-function downloadText(text, filename, mime) {
+export function downloadText(text, filename, mime) {
     const url = URL.createObjectURL(new Blob([text], { type: mime }));
     const anchor = document.createElement('a');
     anchor.href = url;
@@ -83,6 +84,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 +138,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 +166,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 +385,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 +414,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();
@@ -403,6 +444,10 @@ export class Controller {
         if (seq !== (c.solveSeq ?? 0))
             return;
         c.solving = false;
+        // Every solve of a case restates the same findings; they count once.
+        const findings = c.solution?.diagnostics ?? [];
+        if (findings.length)
+            this.app.log.record(findings.map((d) => solveEntry(d, { subject: this.caseName(c) })), { repeat: false });
         const selectionLive = target !== null &&
             this.isActiveSolveCase(c) &&
             ('bus' in target
@@ -557,7 +602,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 +616,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 +728,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 +890,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 +916,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;
@@ -976,6 +1024,7 @@ export class Controller {
             routes += payload.report.matched_branches;
             unmatched += payload.report.unmatched_features;
             warnings.push(...l.diagnostics.map((d) => `${l.name}: ${formatPowerIoDiagnostic(d)}`), ...payload.report.notes.map((n) => `${l.name}: ${n}`));
+            this.logCoordinates(l.name, l.diagnostics, payload.report.notes);
         }
         if (!payload)
             return;
@@ -1049,6 +1098,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 +1171,8 @@ export class Controller {
             'baseSolution',
             'iterations',
             'solveMs',
-            'solveBackend'
+            'solveBackend',
+            'solveDetail'
         ])
             Object.assign(copy, { [key]: source[key] });
         const captured = this.detachedCaseCaptures.get(source);
@@ -1276,7 +1327,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 +1463,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 +1522,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 +1586,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 +1602,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 +1630,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 +1858,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 +1872,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;
@@ -1953,6 +2049,7 @@ export class Controller {
                 const label = summary.name && summary.name !== 'case'
                     ? summary.name
                     : file.name.replace(/\.[^.]+$/, '');
+                this.logImport(file.name, summary);
                 const local = new LocalCase({
                     id,
                     label,
@@ -2152,6 +2249,7 @@ export class Controller {
         const view = coordsKind === 'geographic'
             ? buildGeographicView(graph, payload.geo_layer)
             : buildDiagramView(graph, payload.geo_layer);
+        this.logImport(fileName, summary);
         const c = new MulticonductorCase({
             id: `dist-${++this.localSeq}`,
             label,
@@ -2299,6 +2397,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) => {
@@ -2369,6 +2525,7 @@ export class Controller {
             next = payload.module_json;
             matched += payload.report.matched_buses + payload.report.matched_branches;
             notes.push(`${payload.report.matched_buses} buses, ${payload.report.matched_branches} routes matched; ${payload.report.unmatched_features} unmatched objects`, ...payload.report.notes, ...layer.diagnostics.map(formatPowerIoDiagnostic));
+            this.logCoordinates(layer.name, layer.diagnostics, payload.report.notes);
         }
         if (!payload || !matched)
             throw new Error('No coordinates matched the selected case');
@@ -2595,7 +2752,13 @@ export class Controller {
             ...placeSyntheticTopology(c.topology, { lon: 0, lat: 0 }),
             coordinate_space: 'diagram'
         };
-        return { id: 'study', name: c.name, base_mva: c.base_mva, synthetic_coords: !c.view, ...view };
+        return {
+            id: 'study',
+            name: c.name,
+            base_mva: c.base_mva,
+            synthetic_coords: !c.view,
+            ...view
+        };
     }
     async caseGeographyLayers(c) {
         if (!c.studyInputJson || !c.view)
@@ -2633,15 +2796,46 @@ export class Controller {
             if (snapshot.base_input !== base ||
                 JSON.stringify(snapshot.display_solution) !== JSON.stringify(c.solution))
                 throw new Error('The server case changed. Reload it before saving.');
-            return { input: snapshot.input, solution: snapshot.solution, view: snapshot.view };
+            return {
+                input: snapshot.input,
+                solution: snapshot.solution,
+                view: snapshot.view
+            };
         }
         return { input: base };
     }
+    /** Record what PowerIO and the engine said while reading a case file. */
+    logImport(fileName, summary) {
+        this.app.log.record([
+            ...(summary.diagnostics ?? []).map((d) => powerIoEntry(d, { stage: 'Open', subject: fileName })),
+            ...(summary.warnings ?? []).map((message) => ({
+                severity: 'note',
+                stage: 'Open',
+                source: 'tellegen',
+                subject: fileName,
+                message
+            }))
+        ]);
+    }
+    /** Record a geographic layer's reader findings and placement notes. */
+    logCoordinates(layer, diagnostics, notes) {
+        this.app.log.record([
+            ...(diagnostics ?? []).map((d) => powerIoEntry(d, { stage: 'Coordinates', subject: layer })),
+            ...(notes ?? []).map((message) => ({
+                severity: 'note',
+                stage: 'Coordinates',
+                source: 'tellegen',
+                subject: layer,
+                message
+            }))
+        ]);
+    }
     /** Build a local case from a balanced PowerIO ingest payload without activating
      * it yet; co-dropped placement data is applied before the first solve. */
     localFromBalancedPayload = (fileName, payload) => {
         const { module_json, topology, view, formulation, ...summary } = payload;
         const label = summary.name && summary.name !== 'case' ? summary.name : fileName.replace(/\.[^.]+$/, '');
+        this.logImport(fileName, summary);
         return new LocalCase({
             id: `local-${++this.localSeq}`,
             label,
@@ -2684,7 +2878,11 @@ export class Controller {
                 local.formulation = input.formulation;
             if (input.geoLayer) {
                 await this.applyGeoLayers(local, [
-                    { name: `${input.name}.geo.json`, layer: input.geoLayer, diagnostics: [] }
+                    {
+                        name: `${input.name}.geo.json`,
+                        layer: input.geoLayer,
+                        diagnostics: []
+                    }
                 ]);
             }
             this.placeTopologyAsDiagram(local);
@@ -2736,6 +2934,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`;
@@ -2787,8 +2990,10 @@ export class Controller {
             return [];
         try {
             const exported = await study.export(format);
-            downloadText(exported.text, `${this.caseFileStem(c)}.${exported.extension}`, 'text/plain');
+            const fileName = `${this.caseFileStem(c)}.${exported.extension}`;
+            downloadText(exported.text, fileName, 'text/plain');
             this.app.error = null;
+            this.app.log.record((exported.diagnostics ?? []).map((d) => powerIoEntry(d, { stage: 'Export', subject: fileName })), { repeat: false });
             return exported.diagnostics;
         }
         catch (e) {
@@ -2818,7 +3023,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 +3138,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;
+};