flexdesk 0.16.1 → 0.17.0

package/src/charts/plot_popout_window.js

@@ -13,11 +13,14 @@
  * - Multi-subplot grid layouts (1x1, 1x2, 2x1, 2x2, 1x3, wide-top, wide-bottom)
  * - Series visibility toggle panel
  * - Zoom/pan toolbar with zoom in/out, autoscale, reset
- * - PyWebView integration for file downloads (CSV, PNG)
+ * - CSV and PNG export through the host's dialogs (else a browser download)
  * - NotificationCenter integration for user feedback
  * - Live streaming updates while the data source is running
- * - HP filter trend/cycle decomposition
+ * - Derived series from injected transforms (`seriesTransforms`)
  * - ETL actuals overlay support
+ *
+ * The figures are drawn by renderPlotGrid (plot_grid.js); this window adds the
+ * tabs, the toolbar, the series toggles and the data table around them.
  */
 
 import { ManagedWindow } from '../ui/components/managed_window.js';
@@ -28,17 +31,8 @@ import {
     purge,
     getSeriesColor,
 } from './plotly_wrapper.js';
-import {
-    buildTrace,
-    buildYAxisLayout,
-    buildLegendLayout,
-    buildOverlayShapes,
-} from './chart_types.js';
-import {
-    PLOT_LAYOUTS,
-    migrateData,
-    applyNanHandling,
-} from './plot_config.js';
+import { migrateData } from './plot_config.js';
+import { renderPlotGrid, resolveSeriesData } from './plot_grid.js';
 
 export class PlotPopoutWindow {
     /**
@@ -52,14 +46,29 @@ export class PlotPopoutWindow {
      *        capability backs Export PNG/CSV; absent => Blob download fallback.
      * @param {Function} [options.onClose] - Called when window closes
      * @param {Object} [options.actuals] - ETL overlay data { seriesId: { years, values } }
-     * @param {Function} [options.configRenderer] - (container) => void — renders config panel
+     * @param {Function} [options.configRenderer] - `(container) => { dispose() } | void` —
+     *        renders the Config tab. What it returns is disposed (`dispose()`) when the
+     *        window closes, so an editor drawn there (renderPlotConfigEditor) goes with it.
+     * @param {Object} [options.seriesTransforms] - `{ [id]: transform }` (series_transforms.js);
+     *        absent => no derived series are drawn
+     * @param {string} [options.refreshEvent='data:changed'] - Bus event after which the
+     *        window re-reads `getResults()` and redraws.
+     * @param {{delta?: string|null, complete?: string|null}} [options.streamEvents] - Bus
+     *        events a live data source emits while it runs (`delta`) and when it ends
+     *        (`complete`); the window redraws on each while live update is on.
+     *        There are no default names: without `streamEvents` (or with a name
+     *        left out or given as null) nothing is listened for, and the window
+     *        updates through `refreshEvent` and explicit calls only.
+     * @param {Function} [options.resolveSeries] - `(series, results, subplot) => { y, x? } | null`
+     *        (plot_grid.js); used by the chart and the data table. Default resolveSeriesData.
      */
     constructor({ id, title, plotConfig, getResults, services, host, onClose, actuals,
-                  configRenderer,
+                  configRenderer, seriesTransforms, resolveSeries = resolveSeriesData,
                   // The window used to listen for 'simulation:run:completed' and tell
                   // the user to "run simulation first". A chart window does not know
                   // that its data comes from a simulation; the app that opens it does.
                   refreshEvent = 'data:changed',
+                  streamEvents = {},
                   emptyMessage = 'No data yet.',
                   tableEmptyMessage = 'No data yet.' }) {
         this._id = id;
@@ -71,7 +80,11 @@ export class PlotPopoutWindow {
         this._onClose = onClose ?? (() => {});
         this._actuals = actuals ?? null;
         this._configRenderer = configRenderer ?? null;
+        this._seriesTransforms = seriesTransforms ?? null;
+        this._resolveSeries = resolveSeries;
         this.refreshEvent = refreshEvent;
+        this.streamEvents = Object.freeze({ delta: streamEvents?.delta ?? null,
+                                            complete: streamEvents?.complete ?? null });
         // TWO messages, not one. The chart says "No data — run simulation first."
         // and the data table underneath says "Run simulation to see data". Folding
         // them into a single option would have quietly rewritten one of them, which
@@ -82,12 +95,10 @@ export class PlotPopoutWindow {
 
         this._window = null;
         this._contentEl = null;
-        this._chartDivs = [];
+        this._grid = null;
         this._gridEl = null;
         this._activeTab = 'plot';
         this._eventDisposers = [];
-        this._resizeObserver = null;
-        this._chartCreated = false;
         this._lastResults = null;
 
         // Data table
@@ -103,6 +114,7 @@ export class PlotPopoutWindow {
         this._plotContent = null;
         this._dataContent = null;
         this._configContent = null;
+        this._configHandle = null;
         this._toolbarActions = null;
         this._zoomBtn = null;
         this._panBtn = null;
@@ -118,6 +130,8 @@ export class PlotPopoutWindow {
         this._outsideClickHandler = null;
 
         this._renderPending = false;
+        /** updateConfig() ran since the last #render(); applied even without results. */
+        this._configChanged = false;
 
         // Live-update toggle: when true, window re-renders on streaming events
         this._liveUpdate = true;
@@ -135,7 +149,6 @@ export class PlotPopoutWindow {
         await ensurePlotly();
         this.#createWindow();
         this.#subscribeEvents();
-        this.#setupResizeObserver();
         await this.#render();
     }
 
@@ -146,7 +159,7 @@ export class PlotPopoutWindow {
     /** Update plot config and re-render. */
     updateConfig(plotConfig) {
         this._plotConfig = migrateData(plotConfig);
-        this.#buildSubplotGrid();
+        this._configChanged = true;
         this.#scheduleRender();
     }
 
@@ -279,7 +292,20 @@ export class PlotPopoutWindow {
         this._gridEl.className = 'twm-plot-window-chart';
         this._plotContent.appendChild(this._gridEl);
 
-        this.#buildSubplotGrid();
+        this._grid = renderPlotGrid(this._gridEl, this._plotConfig, null, {
+            resolveSeries: this._resolveSeries,
+            overlays: this._actuals,
+            hiddenSeries: this._hiddenSeries,
+            seriesTransforms: this._seriesTransforms,
+            onTransformError: ({ transformId, traceName, error }) => this._services?.logger?.warn?.(
+                `[PlotPopoutWindow] transform "${transformId}" failed on "${traceName}"`, error),
+            // Popout windows have space — always show the legend.
+            alwaysShowLegend: true,
+            layout: { autosize: true, hovermode: 'x unified' },
+            emptyMessage: this.emptyMessage,
+            onError: ({ index, error }) => this._services?.logger?.warn?.(
+                `[PlotPopoutWindow] subplot ${index + 1} failed to draw`, error),
+        });
 
         // Data tab content
         this._dataContent = document.createElement('div');
@@ -300,7 +326,7 @@ export class PlotPopoutWindow {
             this._configContent.className = 'twm-plot-tab-content';
             this._configContent.setAttribute('data-tab', 'config');
             this._configContent.style.cssText = 'display:none; flex-direction:column; overflow:auto; padding:8px 12px;';
-            this._configRenderer(this._configContent);
+            this._configHandle = this._configRenderer(this._configContent) ?? null;
             content.appendChild(this._configContent);
         }
 
@@ -316,40 +342,6 @@ export class PlotPopoutWindow {
         return container;
     }
 
-    // ── Subplot grid ────────────────────────────────────────────────────
-
-    #buildSubplotGrid() {
-        if (!this._gridEl) return;
-
-        // Purge existing charts
-        for (const div of this._chartDivs) {
-            if (div && window.Plotly) {
-                try { purge(div); } catch (_) {}
-            }
-        }
-        this._gridEl.innerHTML = '';
-        this._chartDivs = [];
-
-        const tmpl = PLOT_LAYOUTS[this._plotConfig.layout] || PLOT_LAYOUTS['1x1'];
-        this._gridEl.style.display = 'grid';
-        this._gridEl.style.gridTemplateColumns = tmpl.grid.columns;
-        this._gridEl.style.gridTemplateRows = tmpl.grid.rows;
-        this._gridEl.style.gap = '4px';
-        this._gridEl.style.height = '100%';
-        this._gridEl.style.width = '100%';
-
-        for (let i = 0; i < tmpl.slots; i++) {
-            const div = document.createElement('div');
-            div.className = 'plot-tile-chart';
-            div.style.gridArea = tmpl.areas[i].gridArea;
-            div.style.minHeight = '0';
-            this._gridEl.appendChild(div);
-            this._chartDivs.push(div);
-        }
-
-        this._chartCreated = false;
-    }
-
     // ── Toolbar helpers ─────────────────────────────────────────────────
 
     #toolbarGroup() {
@@ -370,9 +362,13 @@ export class PlotPopoutWindow {
 
     // ── Plotly toolbar actions ───────────────────────────────────────────
 
+    get #charts() { return this._grid?.charts ?? []; }
+    /** The subplots that show a figure — the grid knows, however it drew them. */
+    get #plottedCharts() { return this._grid?.plotted ?? []; }
+
     #setDragMode(mode) {
-        if (!this._chartCreated) return;
-        for (const div of this._chartDivs) {
+        if (!this.#plottedCharts.length) return;
+        for (const div of this.#charts) {
             if (div._fullLayout) {
                 window.Plotly.relayout(div, { dragmode: mode }).catch(() => {});
             }
@@ -382,7 +378,7 @@ export class PlotPopoutWindow {
     }
 
     #zoom(factor) {
-        for (const div of this._chartDivs) {
+        for (const div of this.#charts) {
             if (!div._fullLayout) continue;
             const xa = div._fullLayout.xaxis;
             const ya = div._fullLayout.yaxis;
@@ -403,7 +399,7 @@ export class PlotPopoutWindow {
     }
 
     #autoscale() {
-        for (const div of this._chartDivs) {
+        for (const div of this.#charts) {
             if (!div._fullLayout) continue;
             window.Plotly.relayout(div, {
                 'xaxis.autorange': true,
@@ -412,20 +408,6 @@ export class PlotPopoutWindow {
         }
     }
 
-    #setupResizeObserver() {
-        if (!this._plotContent) return;
-        this._resizeObserver = createRafResizeObserver(() => {
-            if (this._activeTab === 'plot' && this._chartCreated && window.Plotly) {
-                for (const div of this._chartDivs) {
-                    if (div._fullLayout) {
-                        Plotly.Plots.resize(div).catch(() => {});
-                    }
-                }
-            }
-        });
-        this._resizeObserver.observe(this._plotContent);
-    }
-
     #switchTab(tabName) {
         this._activeTab = tabName;
 
@@ -443,13 +425,7 @@ export class PlotPopoutWindow {
             this._configContent.style.display = tabName === 'config' ? 'flex' : 'none';
         }
 
-        if (tabName === 'plot' && this._chartCreated && window.Plotly) {
-            for (const div of this._chartDivs) {
-                if (div._fullLayout) {
-                    Plotly.Plots.resize(div).catch(() => {});
-                }
-            }
-        }
+        if (tabName === 'plot') this._grid?.resize();
 
         if (tabName === 'data') {
             this.#renderDataTable();
@@ -649,17 +625,16 @@ export class PlotPopoutWindow {
         const { eventBus } = this._services;
         if (!eventBus) return;
 
-        this._eventDisposers.push(
-            eventBus.on('streaming:delta', () => {
-                if (this._liveUpdate) this.#scheduleRender();
-            })
-        );
-        this._eventDisposers.push(
-            eventBus.on('streaming:complete', () => {
-                if (this._liveUpdate) this.#scheduleRender();
-            })
-        );
-        // Final analytics arrive asynchronously after streaming:complete
+        const { delta, complete } = this.streamEvents;
+        for (const name of new Set([delta, complete])) {
+            if (!name) continue;
+            this._eventDisposers.push(
+                eventBus.on(name, () => {
+                    if (this._liveUpdate) this.#scheduleRender();
+                })
+            );
+        }
+        // Final analytics arrive asynchronously after the stream's complete event
         // (backend fetch + transform). Without this, the popout window may
         // render stale data from a previous run when the dashboard tab
         // didn't receive streaming deltas (e.g. user was on another tab).
@@ -699,7 +674,21 @@ export class PlotPopoutWindow {
         if (!this._window?.isVisible) return;
 
         const results = this._getResults?.();
-        if (!results) return;
+        const configChanged = this._configChanged;
+        this._configChanged = false;
+        if (!results) {
+            // No data yet: the figures already drawn stay, unless the layout or
+            // the subplots changed, in which case the grid is rebuilt for them.
+            if (configChanged) {
+                await this._grid.update({
+                    plotConfig: this._plotConfig,
+                    results: null,
+                    overlays: this._actuals,
+                    hiddenSeries: this._hiddenSeries,
+                });
+            }
+            return;
+        }
 
         this._lastResults = results;
 
@@ -707,7 +696,13 @@ export class PlotPopoutWindow {
         this.#collectSeriesInfo();
 
         // Render all subplot charts
-        this.#renderAllCharts(results);
+        await this._grid.update({
+            plotConfig: this._plotConfig,
+            results,
+            overlays: this._actuals,
+            hiddenSeries: this._hiddenSeries,
+        });
+        if (!this._window) return;
 
         // Update table data
         this.#updateTableData(results);
@@ -737,7 +732,7 @@ export class PlotPopoutWindow {
                     this._allSeriesLabels.push(label);
 
                     // Include overlay in toggle list
-                    if (s.overlay?.etlKey) {
+                    if (s.overlay) {
                         const ovLabel = s.overlay.label || `${label} (actual)`;
                         this._allSeriesInfo.push({
                             label: ovLabel,
@@ -778,204 +773,6 @@ export class PlotPopoutWindow {
         }
     }
 
-    #renderAllCharts(results) {
-        if (!window.Plotly) return;
-
-        const subplots = this._plotConfig.subplots ?? [];
-        for (let i = 0; i < this._chartDivs.length; i++) {
-            const chartDiv = this._chartDivs[i];
-            const sp = subplots[i];
-            if (!chartDiv) continue;
-            if (!sp) {
-                chartDiv.innerHTML = '<div class="twm-plot-no-data" style="color:rgba(255,255,255,0.3);text-align:center;padding:16px;">No subplot configured.</div>';
-                continue;
-            }
-            this.#renderSubplotChart(chartDiv, sp, results);
-        }
-    }
-
-    async #renderSubplotChart(chartDiv, sp, results) {
-        const { time, series } = results;
-        const traces = [];
-        const layoutAxes = {};
-        const yRefByAxisId = {};
-        let axisCount = 0;
-
-        for (const axis of sp.yAxes ?? []) {
-            axisCount++;
-            const yAxisKey = axisCount === 1 ? 'yaxis' : `yaxis${axisCount}`;
-            const yRef = axisCount === 1 ? 'y' : `y${axisCount}`;
-            if (axis.id) yRefByAxisId[axis.id] = yRef;
-
-            layoutAxes[yAxisKey] = buildYAxisLayout({
-                axisId: yAxisKey,
-                title: axis.label || '',
-                position: axis.position || 'left',
-                scaleType: axis.scale || 'linear',
-                min: axis.min,
-                max: axis.max,
-                showGrid: (sp.yAxes ?? []).length === 1,
-                axisPosition: axisCount > 1 ? (axis.position === 'right' ? 1 : 0) : null,
-            });
-
-            for (const s of axis.series ?? []) {
-                if (!s.variable) continue;
-
-                const label = s.label || s.variable;
-
-                // Skip hidden series
-                if (this._hiddenSeries.has(label)) continue;
-
-                // Resolve variable: try result key (paper multi-scenario), exact, then bare (without namespace prefix)
-                let rawY = series?.[s._resultKey ?? s.variable];
-                if (!rawY && s._resultKey) {
-                    rawY = series?.[s.variable];
-                }
-                if (!rawY) {
-                    const dotIdx = s.variable.indexOf('.');
-                    if (dotIdx >= 0) rawY = series?.[s.variable.slice(dotIdx + 1)];
-                }
-                if (!rawY) continue;
-
-                const y = Array.isArray(rawY) ? applyNanHandling(rawY, sp.nanHandling ?? 'gap', time) : rawY;
-                const seriesTime = s._resultTime ?? time;
-                traces.push(buildTrace({
-                    chartType: sp.chartType || 'line',
-                    x: seriesTime,
-                    y,
-                    name: label,
-                    color: s.color,
-                    lineWidth: s.lineWidth ?? 2,
-                    lineStyle: s.lineStyle ?? 'solid',
-                    interpolation: sp.interpolation ?? 'linear',
-                    yAxisId: yRef,
-                    showMarkers: sp.showDataPoints ?? false,
-                    stackGroup: s.stackGroup ?? null,
-                }));
-
-                // Per-series overlay trace (ETL actuals)
-                if (s.overlay?.etlKey && this._actuals?.[s.id]) {
-                    const ovLabel = s.overlay.label || `${label} (actual)`;
-                    if (!this._hiddenSeries.has(ovLabel)) {
-                        const act = this._actuals[s.id];
-                        if (act?.years?.length) {
-                            const ov = s.overlay;
-                            const dashMap = { dashed: 'dash', dotted: 'dot', solid: 'solid' };
-                            traces.push({
-                                type: 'scatter',
-                                mode: ov.mode || 'markers+lines',
-                                x: act.years,
-                                y: act.values,
-                                name: ov.label || `${label} (actual)`,
-                                yaxis: yRef === 'y' ? undefined : yRef,
-                                line: {
-                                    color: ov.color || s.color,
-                                    width: ov.lineWidth ?? 2,
-                                    dash: dashMap[ov.lineStyle] || 'dash',
-                                },
-                                marker: {
-                                    color: ov.color || s.color,
-                                    size: 4,
-                                    symbol: 'circle',
-                                },
-                                showlegend: true,
-                            });
-                        }
-                    }
-                }
-            }
-        }
-
-        // HP filter traces
-        if ((sp.showHpTrend || sp.showHpCycle) && window.pywebview?.api?.hp_filter) {
-            const hpLambda = sp.hpLambda ?? 1600;
-            for (const trace of [...traces]) {
-                if (trace.type && trace.type !== 'scatter' && trace.type !== 'scattergl') continue;
-                try {
-                    const hpResult = await window.pywebview.api.hp_filter({
-                        data: trace.y,
-                        lambda: hpLambda,
-                    });
-                    if (!hpResult?.ok) continue;
-                    const { trend, cycle } = hpResult;
-                    const origColor = trace.line?.color || trace.marker?.color || getSeriesColor(0);
-                    if (sp.showHpTrend && trend) {
-                        traces.push({
-                            x: trace.x, y: trend, type: 'scatter', mode: 'lines',
-                            name: `${trace.name} (HP Trend)`,
-                            yaxis: trace.yaxis || 'y',
-                            line: { color: origColor, width: 2, dash: 'dash' },
-                            showlegend: true,
-                        });
-                    }
-                    if (sp.showHpCycle && cycle) {
-                        traces.push({
-                            x: trace.x, y: cycle, type: 'scatter', mode: 'lines',
-                            name: `${trace.name} (HP Cycle)`,
-                            yaxis: trace.yaxis || 'y',
-                            line: { color: origColor, width: 1, dash: 'dot' },
-                            showlegend: true,
-                        });
-                    }
-                } catch (_) { /* ignore HP filter failures */ }
-            }
-        }
-
-        if (traces.length === 0 && this._hiddenSeries.size === 0) {
-            chartDiv.innerHTML = `<div class="twm-plot-no-data" style="color:rgba(255,255,255,0.3);text-align:center;padding:16px;font-size:11px;">${this.emptyMessage}</div>`;
-            return;
-        }
-
-        // Popout windows have space — always show legend
-        const legendPos = sp.legendPosition === 'hidden' ? 'top' : (sp.legendPosition ?? 'top');
-        const legend = buildLegendLayout(legendPos);
-
-        // Clip the x-axis to the data's time range so overlays don't run past t0–t1
-        const xRange = time?.length >= 2 ? [time[0], time[time.length - 1]] : undefined;
-
-        const { shapes, annotations } = buildOverlayShapes({
-            referenceLines: sp.referenceLines,
-            shadedBands: sp.shadedBands,
-            yRefByAxisId,
-        });
-
-        const layout = {
-            ...layoutAxes,
-            ...(shapes.length ? { shapes } : {}),
-            ...(annotations.length ? { annotations } : {}),
-            xaxis: {
-                gridcolor: 'rgba(255,255,255,0.05)',
-                linecolor: 'rgba(255,255,255,0.08)',
-                tickcolor: 'rgba(255,255,255,0.3)',
-                zerolinecolor: 'rgba(255,255,255,0.06)',
-                automargin: true,
-                ...(xRange ? { range: xRange } : {}),
-            },
-            ...legend,
-            paper_bgcolor: 'transparent',
-            plot_bgcolor: 'transparent',
-            font: { family: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif', color: '#cccccc', size: 11 },
-            margin: { t: 10, r: 20, b: 40, l: 50 },
-            hoverlabel: {
-                bgcolor: '#1e2228',
-                bordercolor: '#444444',
-                font: { family: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif', color: '#cccccc' },
-            },
-            autosize: true,
-            hovermode: 'x unified',
-        };
-
-        // Guard: skip if div is detached or zero-size
-        if (!chartDiv.isConnected || chartDiv.offsetWidth === 0) return;
-
-        try {
-            await Plotly.react(chartDiv, traces, layout, { responsive: true, displayModeBar: false });
-            this._chartCreated = true;
-        } catch (_) {
-            // Plotly can throw if div is removed mid-render
-        }
-    }
-
     // ── Data table ──────────────────────────────────────────────────────
 
     #updateTableData(results) {
@@ -987,7 +784,7 @@ export class PlotPopoutWindow {
 
         const headers = ['Time'];
         const seriesColumns = [];
-        const { time, series } = results;
+        const { time } = results;
         const subplots = this._plotConfig.subplots ?? [];
 
         for (const sp of subplots) {
@@ -995,14 +792,7 @@ export class PlotPopoutWindow {
                 for (const s of axis.series ?? []) {
                     if (!s.variable) continue;
                     const label = s.label || s.variable;
-                    let rawY = series?.[s._resultKey ?? s.variable];
-                    if (!rawY && s._resultKey) {
-                        rawY = series?.[s.variable];
-                    }
-                    if (!rawY) {
-                        const dotIdx = s.variable.indexOf('.');
-                        if (dotIdx >= 0) rawY = series?.[s.variable.slice(dotIdx + 1)];
-                    }
+                    const rawY = this._resolveSeries(s, results, sp)?.y;
                     if (!rawY) continue;
                     headers.push(label);
                     seriesColumns.push(rawY);
@@ -1108,10 +898,9 @@ export class PlotPopoutWindow {
     }
 
     async #downloadPNG() {
-        // For multi-subplot, capture the grid container as a whole
-        // Fall back to first chart div if only one subplot
-        const targetDiv = this._chartDivs.length === 1 ? this._chartDivs[0] : this._chartDivs[0];
-        if (!targetDiv || !window.Plotly || !this._chartCreated) {
+        // The first subplot that shows a figure.
+        const targetDiv = this.#plottedCharts[0];
+        if (!targetDiv || !window.Plotly) {
             this.#notify('Download', 'Plot not ready', 'warn');
             return;
         }
@@ -1170,26 +959,24 @@ export class PlotPopoutWindow {
 
         this.#hideSeriesPanel();
 
-        if (this._resizeObserver) {
-            this._resizeObserver.disconnect();
-            this._resizeObserver = null;
-        }
-
         for (const disposer of this._eventDisposers) {
             try { disposer?.dispose?.(); } catch (_) {}
         }
         this._eventDisposers = [];
 
-        for (const div of this._chartDivs) {
-            if (div && window.Plotly) {
-                try { purge(div); } catch (_) {}
-            }
+        // What configRenderer returned (an editor with dropdowns in document.body,
+        // say) goes with the window.
+        try { this._configHandle?.dispose?.(); } catch (error) {
+            this._services?.logger?.warn?.('[PlotPopoutWindow] the config panel failed to dispose', error);
         }
+        this._configHandle = null;
+
+        this._grid?.dispose();
+        this._grid = null;
 
         this._window = null;
         this._contentEl = null;
         this._gridEl = null;
-        this._chartDivs = [];
         this._plotTab = null;
         this._dataTab = null;
         this._plotContent = null;
@@ -1204,7 +991,6 @@ export class PlotPopoutWindow {
         this._hiddenSeries = null;
         this._allSeriesInfo = null;
         this._allSeriesLabels = null;
-        this._chartCreated = false;
         this._lastResults = null;
     }
 }

package/src/charts/plotly_wrapper.js

@@ -88,7 +88,7 @@ if (typeof HTMLCanvasElement !== 'undefined') {
 }
 
 /**
- * Dark theme layout defaults matching EcoSim UI
+ * Dark theme layout defaults matching the shell's dark UI
  */
 export const DARK_THEME_LAYOUT = {
     paper_bgcolor: 'transparent',
@@ -146,6 +146,9 @@ export const DARK_THEME_LAYOUT = {
     }
 };
 
+/** The PNG export's file name (without extension) when the embedder names none. */
+export const DEFAULT_CHART_EXPORT_FILENAME = 'chart';
+
 /**
  * Default Plotly config options
  */
@@ -156,11 +159,28 @@ export const DEFAULT_CONFIG = {
     scrollZoom: true,       // Allow zoom with scroll wheel instead
     toImageButtonOptions: {
         format: 'png',
-        filename: 'ecosim_chart',
+        filename: DEFAULT_CHART_EXPORT_FILENAME,
         scale: 2
     }
 };
 
+/**
+ * Name the file a chart's PNG export saves as (Plotly adds `.png`). Applies to
+ * every chart created afterwards through DEFAULT_CONFIG; a chart's own
+ * `config.toImageButtonOptions` still wins.
+ *
+ * @param {string} [filename=DEFAULT_CHART_EXPORT_FILENAME]
+ */
+export function setChartExportFilename(filename = DEFAULT_CHART_EXPORT_FILENAME) {
+    DEFAULT_CONFIG.toImageButtonOptions.filename =
+        (typeof filename === 'string' && filename) ? filename : DEFAULT_CHART_EXPORT_FILENAME;
+}
+
+/** @returns {string} The PNG export's file name (without extension). */
+export function getChartExportFilename() {
+    return DEFAULT_CONFIG.toImageButtonOptions.filename;
+}
+
 /**
  * Load Plotly.js from CDN.
  * Uses singleton pattern to avoid multiple loads.