@tellegen/svelte 0.2.0 → 0.4.0

package/dist/controller.svelte.d.ts

@@ -1,14 +1,19 @@
 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 BrowserStudy, type Formulation, type SensTarget } from '@tellegen/engine';
+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';
 /** 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. */
 type GeoLayerFile = {
     name: string;
     layer: string;
-    warnings: string[];
+    diagnostics: PowerIoDiagnostic[];
+};
+type SavedCaseCapture = {
+    input: string;
+    solution?: string;
+    view?: import('@tellegen/engine').StudyView;
 };
 /** A lowered analysis row is view-only only when a current producer says so;
  * absence keeps payloads from older compatible engine/server versions editable. */
@@ -23,23 +28,54 @@ type DemandRangeAnchor = {
 };
 export interface ControllerOptions {
     api?: TellegenApiClient;
-    apiBase?: string;
+    /** Backend base path. `null` means there is no backend: no client is
+     * created and nothing is ever fetched. */
+    apiBase?: string | null;
+    /** Whether `load()` fetches the bundled cases. Default `true`. With
+     * `false`, `load()` only marks the shell loaded and frames the map. */
+    loadDefaultCases?: boolean;
+    mcTransport?: Pick<EngineTransport, 'solveMcModule' | 'applyMcGeo'> & Partial<Pick<EngineTransport, 'solveMcStudy' | 'applyMcStudyGeo' | 'createMcPfSession'>>;
+}
+/** Input to `Controller.openBalancedModule` and `replaceLocalCase`: a
+ * balanced (transmission) powerio module, either as its JSON text or as the
+ * payload the engine's `ingestCase` already produced for it. */
+export interface OpenBalancedModuleInput {
+    /** Case label; also the stem of the `.pio.json` file name the shell shows. */
+    name: string;
+    /** Module JSON, ingested through the engine. Ignored when `payload` is set. */
+    moduleJson?: string;
+    /** An already ingested balanced payload; skips the engine round trip. */
+    payload?: IngestedCase;
+    /** A `.geo.json` layer document, for a module that carries no coordinates. */
+    geoLayer?: string;
+    /** Overrides the formulation the module declares. */
+    formulation?: Formulation;
+    /** Default `true`: add the case, make it active, and start its browser
+     * solve. With `false` the prepared case is returned and not added. */
+    activate?: boolean;
+    /** Default `true`: fly the map to the case when it is activated. */
+    frame?: boolean;
 }
 export declare class Controller {
     app: AppState;
-    api: TellegenApiClient;
+    /** `null` when the controller was created with `apiBase: null`; every
+     * server path then reports "compute off" instead of fetching. */
+    api: TellegenApiClient | null;
+    readonly loadDefaultCases: boolean;
+    mcTransport: Pick<EngineTransport, 'solveMcModule' | 'applyMcGeo'> & Partial<Pick<EngineTransport, 'solveMcStudy' | 'applyMcStudyGeo' | 'createMcPfSession'>>;
     abort: AbortController | null;
     sensitivity429Until: number;
     serverComputeOff: boolean;
     caseStudies: WeakMap<SolvableCase, {
         study: BrowserStudy;
-        networkJson: string;
+        studyInputJson: string;
         formulation: Formulation;
         baseSolution: Solution;
     }>;
+    private detachedCaseCaptures;
     studyUnavailable: WeakMap<SolvableCase, string>;
     studyBuilds: WeakMap<SolvableCase, {
-        networkJson: string;
+        studyInputJson: string;
         formulation: Formulation;
         token: object;
         promise: Promise<BrowserStudy | null>;
@@ -74,6 +110,7 @@ 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;
+    bumpRevision(c: SolvableCase): void;
     setNearbyRangeAnchor(c: SolvableCase, bus: number, delta?: number): void;
     beginBusSelection(c: SolvableCase, busId: number): {
         ac: AbortController;
@@ -90,12 +127,12 @@ export declare class Controller {
     rememberHiddenDefaultCase(id: string): void;
     localNetwork(c: LocalCase): Network | null;
     maybeStartLocalSolve(id: string): void;
-    getStudy(c: SolvableCase, networkJson: string): Promise<BrowserStudy | null>;
-    browserSensitivity(c: SolvableCase, networkJson: string, target: SensTarget): Promise<SensitivityColumn | null>;
+    getStudy(c: SolvableCase, studyInputJson: string): Promise<BrowserStudy | null>;
+    browserSensitivity(c: SolvableCase, studyInputJson: string, target: SensTarget): Promise<SensitivityColumn | null>;
     disposeStudy(c: SolvableCase): void;
     acceptSensitivity(c: SolvableCase, col: SensitivityColumn | null, target: SensTarget | null, sensitivitySeq?: number): void;
     finishSolve(c: SolvableCase, seq: number, target: SensTarget | null): void;
-    ensureNetworkJson(c: SolvableCase): Promise<string | null>;
+    ensureStudyInputJson(c: SolvableCase): Promise<string | null>;
     previewDeltas(c: SolvableCase, bus: number, value: number): {
         [x: string]: number;
         [x: number]: number;
@@ -187,11 +224,15 @@ export declare class Controller {
     removeBackendCase: (c: CaseState, event?: MouseEvent) => Promise<void>;
     activateLocal: (c: LocalCase) => void;
     removeLocalCase: (c: LocalCase, event?: MouseEvent) => Promise<void>;
-    addAndActivateLocal: (c: LocalCase) => void;
+    /** Add a prepared local case, make it active, frame it (unless `frame` is
+     * false) and start its browser solve. */
+    addAndActivateLocal: (c: LocalCase, options?: {
+        frame?: boolean;
+    }) => void;
     placeLocalCase: (lon: number, lat: number) => Promise<void>;
     /** Write the case's on-screen layout into its network payload
      * (`Bus.location` with `synthetic` provenance — the engine also accepts
-     * `manual`, which round trips through restored packages), so saves,
+     * `manual`, which round trips through saved PowerIO modules), so saves,
      * exports, and the `.geo.json` download carry it. Best effort: on an
      * engine failure the view still renders, only the layout's persistence is
      * lost. */
@@ -205,7 +246,7 @@ export declare class Controller {
      * wins on shared elements). The engine owns matching and the network becomes
      * the single owner of the coordinates: matched points land in
      * `Bus.location`, routes in `Branch.route`, and the refreshed
-     * `network_json` replaces the case payload — so a saved package or export
+     * `module_json` replaces the case IR — so a saved module or export
      * carries exactly what is on screen. A live Study is synced the same way.
      * Throws when a layer matches nothing. */
     applyGeoLayers: (c: LocalCase, layers: GeoLayerFile[]) => Promise<void>;
@@ -213,10 +254,12 @@ export declare class Controller {
      * the case's network and view, provenance flips to the geographic source,
      * and the warnings panel gets the placement summary. */
     private adoptGeoPayload;
-    /** Keep a live Study's base network in step with a geo change (locations
-     * are metadata the model never reads, so nothing re-solves), and re-key its
-     * cache entry so the next solve reuses it instead of rebuilding. */
-    private syncCachedStudy;
+    /** Update an existing numerical Study after the base input receives geographic data. */
+    private syncStudyGeo;
+    private caseEditKey;
+    private localSidecarCopy;
+    private stageLocalSidecars;
+    private attachSidecarsToSelected;
     applyGeoLayersToExisting: (layers: GeoLayerFile[]) => Promise<void>;
     /** Ask the map to frame the selected branch and wait for the camera to land,
      * capped by FOCUS_SETTLE_CAP_MS and cut short by the selection's abort. */
@@ -232,7 +275,7 @@ export declare class Controller {
      * transient (a wasm chunk or case JSON fetch), so say what is known and keep
      * the retry meaningful. */
     private computeOffNotice;
-    /** The one server ∂LMP/∂parameter request a selection may make: the
+    /** The one server nodal-value/parameter request a selection may make: the
      * reconciliation path when the browser Study produced no column for a DC OPF
      * case. Never retries on its own: a second request inside the same rate limit
      * window is a guaranteed rejection, and the retry button covers the user
@@ -267,6 +310,7 @@ export declare class Controller {
     commitDelta: (value: number) => void;
     finishDemandInput: (value: number) => void;
     resetCase: (c: SolvableCase) => void;
+    /** Rebuild the numerical Study for a selected calculation at the current demand. */
     changeFormulation: (c: SolvableCase, next: Formulation) => void;
     /** Parse dropped files in the browser via the powerio wasm module. Case
      * files (.m, .raw, .aux, .epc, .pwb) become local networks; geographic files can
@@ -279,12 +323,12 @@ export declare class Controller {
      * the first matching PowerWorld display. A failed geographic join keeps the
      * parsed case and returns the user-facing placement error. */
     private prepareDroppedLocal;
-    /** Fill a coordinate-less case's positions from a co-dropped PowerWorld
-     * `.pwd`: the display's substation points project to approximate
-     * longitude/latitude and join onto buses through the `SubNum` extras key.
-     * The first display that joins wins; one that matches nothing stays
-     * available as its own preview entry, and the case stays placeable. */
+    /** A case that still has no geometry gets a connectivity layout as its
+     * diagram, so it can render and solve without a placement step. */
+    private placeTopologyAsDiagram;
+    /** Retain diagram geometry separately from the electrical case's geographic data. */
     private fillFromDisplaySibling;
+    setCaseDisplayMode: (c: LocalCase, mode: "geographic" | "diagram") => void;
     /** Route a dropped `.json` by its content. Recognized payloads return without
      * mutating case state so co-dropped sidecars can be applied first; unrouted
      * content returns the bytes already read for the geographic fallback. */
@@ -292,10 +336,30 @@ export declare class Controller {
     /** Parse a dropped OpenDSS `.dss` file into a multiconductor viewing case.
      * Returns true when a case landed; a parse failure sets the panel error. */
     private ingestDistFile;
-    /** Build a `MulticonductorCase` from an ingest payload and make it active.
-     * Geographic cases place immediately; planar/synthetic cases enter placement
-     * (a map click or "place on map") so the user picks their center. */
+    /** Retain parsed electrical inputs and draw each declared coordinate space directly. */
     private addMultiCase;
+    /** Compute terminal quantities only for the retained input and current case revision. */
+    solveMultiCase: (c: MulticonductorCase, options?: McPfOptions, signal?: AbortSignal) => Promise<McPfSummary>;
+    /** Materialize the current retained operating point only when a portable
+     * snapshot is actually needed (save/export/geography). */
+    snapshotMultiCase: (c: MulticonductorCase) => Promise<McStudySnapshot>;
+    /** One bus's terminals and a page of equipment ports for the displayed
+     * 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>;
+    /** Every terminal's identity, voltage, and injected current, as numeric
+     * arrays of interleaved `[re, im]` values. */
+    multiTerminalTable: (c: MulticonductorCase) => Promise<{
+        ids: Array<[string, string]>;
+        voltages: Float64Array;
+        currents: Float64Array;
+    } | null>;
+    /** Apply coordinates atomically to the explicitly selected conductor-resolved case. */
+    applyMultiGeoLayers: (c: MulticonductorCase, layers: GeoLayerFile[]) => Promise<void>;
+    /** Stage an absolute load-branch P/Q edit and coalesce rapid UI changes into
+     * one retained-factor warm solve. */
+    queueMultiLoadPower: (c: MulticonductorCase, load: string, branch: number, p_w: number, q_var: number) => void;
+    private flushMultiLoadPowers;
     /** Make a multiconductor case active, framing it when it is placed. */
     activateMulti: (c: MulticonductorCase) => void;
     /** Select a bus in a multiconductor case: its terminal stack and incident
@@ -313,21 +377,38 @@ export declare class Controller {
     /** The unified map click-to-place: a pending multiconductor case takes the
      * click first, otherwise a pending local case does. */
     placeCase: (lon: number, lat: number) => void;
-    /** Build a local case from a bare balanced ingest payload without activating
+    projectStudyInput(input: string, layer?: string): Promise<Network>;
+    caseGeographyLayers(c: LocalCase): Promise<string[]>;
+    /** Capture a matching cached result without constructing or solving a model. */
+    captureSavedCase(c: SolvableCase): Promise<SavedCaseCapture>;
+    /** 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;
-    /** Build a local case from a saved package, including its edit state and
-     * formulation, without activating it until sidecars have been applied. */
-    private localFromPackage;
+    /** Ingest module text through the engine and require a balanced network. */
+    private ingestBalancedModule;
+    /** Open a balanced powerio module from memory, the programmatic twin of
+     * dropping a `.pio.json` file: ingest (unless `payload` is given), apply an
+     * optional geographic layer, lay out a module without coordinates as a
+     * diagram, then add and activate it. Resolves to the new case; throws when
+     * the module is not a balanced network or the geographic layer matches
+     * nothing. */
+    openBalancedModule: (input: OpenBalancedModuleInput) => Promise<LocalCase>;
+    /** Swap a local case for a new module in place: same slot in the case list,
+     * same formulation unless `input.formulation` says otherwise, same display
+     * mode when the new case supports it, and the selected bus kept when the
+     * new case has it. The previous case's Study is freed. */
+    replaceLocalCase: (previous: LocalCase, input: OpenBalancedModuleInput) => Promise<LocalCase>;
     /** Build (or reuse) the case's Study and commit it at the current edit state, so a
      * save or export captures exactly what is on screen. Null (with an error set) when no
-     * network or Study is available. */
-    private syncedStudy;
-    /** Save the active study as a `.pio.json` package and download it. */
-    saveStudyPackage: (c: SolvableCase) => Promise<void>;
-    /** Export the active study's committed state to `format` and download it. Returns the
-     * writer's fidelity warnings so the caller can surface them. */
-    exportStudyAs: (c: SolvableCase, format: string) => Promise<string[]>;
+     * PowerIO module or Study is available. */
+    syncedStudy: (c: SolvableCase) => Promise<BrowserStudy | null>;
+    /** Save the materialized case as a retained PowerIO module. */
+    saveCaseModule: (c: SolvableCase) => Promise<void>;
+    /** Save the exact DC OPF result with the materialized problem instance it solved. */
+    saveSolutionModule: (c: SolvableCase) => Promise<void>;
+    /** Export the active study's committed state to `format` and download it.
+     * Returns this output operation's structured diagnostics. */
+    exportCaseAs: (c: SolvableCase, format: string) => Promise<PowerIoDiagnostic[]>;
     /** A filesystem-safe base name for a downloaded case file. */
     private caseFileStem;
     setDemandRangeMode: (mode: DemandRangeMode) => void;