qplotter 1.6.0b3__py3-none-any.whl

qplot/windows/_plot_actions.py

@@ -0,0 +1,2695 @@
+import os
+from functools import wraps
+from inspect import signature
+
+import numpy as np
+import pandas as pd
+from PyQt6 import QtCore
+
+from qplot.datahandling.dimensions import (
+    MAX_SUPPORTED_PLOT_DIMENSIONS,
+    unsupported_plot_message,
+)
+from qplot.datahandling.file_identity import (
+    DatabaseInstance,
+    logical_database_path,
+)
+from qplot.datahandling.parameter_data import (
+    concatenate_record_samples,
+    parameter_data_for_export,
+)
+from qplot.datahandling.readonly import (
+    DatabaseInstanceChangedError,
+    load_by_guid_read_only,
+)
+from qplot.datahandling.trusted_live_service import (
+    SNAPSHOT_FALLBACK_MODE,
+    TRUSTED_LIVE_MODE,
+)
+from qplot.diagnostics import log_exception
+
+from ._dataset_handle import (
+    DatasetHandle,
+    DatasetKey,
+    TraceKey,
+    bind_dataset_key_to_current_source,
+    close_dataset_connection,
+    dataset_key_matches_current_source,
+)
+from ._export_paths import choose_export_path, write_export_atomically
+from ._plot2d_layers import _heatmap_layer_compatibility, _window_display_unit
+from ._plot_refresh import plot_refresh_required
+from ._refresh_interval import refresh_interval_value
+from ._subplots.subplot1d import (
+    _subplot_axis_order,
+    _subplot_shared_parameter,
+)
+from .plot1d import plot1d
+from .plot2d import plot2d
+
+
+def _trusted_plot_action(method):
+    """Resume an explicit UI action only after broker metadata is available."""
+    call_signature = signature(method)
+
+    @wraps(method)
+    def invoke(self, *args, **kwargs):
+        arguments = call_signature.bind(self, *args, **kwargs).arguments
+        target = arguments.get("source_identity", arguments.get("guid"))
+        if self._defer_trusted_plot_action(
+            target, lambda: invoke(self, *args, **kwargs),
+        ):
+            return
+        return method(self, *args, **kwargs)
+    return invoke
+
+
+def _plot_has_trace_window(target, candidate):
+    """Return whether a source window is already represented on a plot."""
+
+    checker = getattr(target, "_has_trace_window", None)
+    if callable(checker):
+        return checker(candidate)
+    return candidate.label in target.lines
+
+
+def _combo_index_for_data(combo, value):
+    """Return the first combo row whose Python user data equals ``value``."""
+
+    count = getattr(combo, "count", None)
+    item_data = getattr(combo, "itemData", None)
+    if not callable(count) or not callable(item_data):
+        return -1
+
+    for index in range(count()):
+        if item_data(index) == value:
+            return index
+    return -1
+
+
+def _exportable_measurement_params(dataset):
+    """Return dependent values, then standalone values, in run order."""
+    parameters = dataset.get_parameters()
+    setpoint_names = {
+        name
+        for param in parameters
+        for name in param.depends_on_
+    }
+    dependent = [param for param in parameters if param.depends_on_]
+    standalone = [
+        param for param in parameters
+        if not param.depends_on_ and param.name not in setpoint_names
+    ]
+    return dependent + standalone
+
+
+def _csv_scalar_samples(values):
+    """Flatten a record, including arrays held in NumPy object cells."""
+    array = np.asarray(values)
+    if not array.dtype.hasobject:
+        return array.ravel()
+    samples = []
+    for value in array.ravel():
+        if isinstance(value, (np.ndarray, list, tuple)):
+            samples.extend(_csv_scalar_samples(value))
+        else:
+            samples.append(value)
+    # These cells can mix signed/unsigned integers (or integers and floats).
+    # Inferring a dtype again would undo extraction's precision protection.
+    return np.asarray(samples, dtype=object)
+
+
+def _csv_scalar_columns(param_data):
+    """Align samples within each QCoDeS record before joining records."""
+    arrays = {name: np.asarray(values) for name, values in param_data.items()}
+    if not arrays:
+        return {}
+    # Regular, already aligned columns need no record-by-record expansion.
+    if (
+            len({values.shape for values in arrays.values()}) == 1
+            and all(not values.dtype.hasobject for values in arrays.values())
+            ):
+        return {name: values.ravel() for name, values in arrays.items()}
+
+    chunks = {name: [] for name in arrays}
+    for record in zip(*arrays.values(), strict=True):
+        samples = {
+            name: _csv_scalar_samples(values)
+            for name, values in zip(arrays, record, strict=True)
+        }
+        sample_count = max(values.size for values in samples.values())
+        for name, values in samples.items():
+            if values.size == sample_count:
+                chunks[name].append(values)
+            elif values.size == 1:
+                chunks[name].append(np.repeat(values, sample_count))
+            else:
+                raise ValueError(
+                    f"Cannot align CSV record column {name}: "
+                    f"{values.size} samples instead of {sample_count}."
+                )
+    return {
+        name: concatenate_record_samples(parts) if parts else np.array([], dtype=arrays[name].dtype)
+        for name, parts in chunks.items()
+    }
+
+
+class PlotActionsMixin:
+    """
+    Plot launching, preview plotting, CSV export, and plot dataset tracking.
+
+    The mixin expects the owning window to provide MainWindow's widgets and
+    state, including windows, dataset_holder, config, threadPool, and status
+    helpers.
+    """
+
+    _selected_dataset_key: DatasetKey | None
+
+    def _defer_trusted_plot_action(self, target, resume):
+        if getattr(self, "_database_access_mode", None) != TRUSTED_LIVE_MODE:
+            return False
+        # Qt's str signal converts the run table's None argument to "".
+        # Both spellings select the current run, just as openPlot does.
+        if target == "":
+            target = None
+        selection = ((getattr(self, "selected_run_id", None),
+                      getattr(self, "_selected_run_guid", None))
+                     if target is None else None)
+        if target is None:
+            metadata = self._run_metadata_for_id(getattr(self, "selected_run_id", None))
+            target = metadata.get("guid") or getattr(self, "_selected_run_guid", None)
+        if not target:
+            return False
+        key = target if isinstance(target, DatasetKey) else self._current_dataset_key(target)
+        if (getattr(self, "ds", None) is not None
+                and getattr(self, "_selected_dataset_key", None) == key):
+            return False
+        if not self._generation_gate_allows_action(key.database_path, "opening plots"):
+            return True
+        try:
+            self._ensure_dataset_key_can_be_read(key)
+        except Exception as error:
+            self.show_error("Plot Load Failed", "Could not open the selected source.", str(error))
+            return True
+        ready = getattr(self, "_trusted_plot_ready", {})
+        if key in ready or self._dataset_handle_for_key(key) is not None:
+            return False
+        service = getattr(self, "_trusted_read_service", None)
+        if (service is None or service.closing or service.closed
+                or service.database_instance.identity != key.database_identity):
+            self.show_error("Plot Load Failed", "The trusted plot session is unavailable.",
+                            "Reopen the source to start a new trusted session.")
+            return True
+        pending = getattr(self, "_trusted_plot_pending", None)
+        if pending is None:
+            pending = self._trusted_plot_pending = set()
+        if len(pending) >= 16:
+            self.show_status("Wait for the pending plots to open.", 5000)
+            return True
+        try:
+            request = service.submit_plot_dataset(key.guid)
+        except Exception as error:
+            self.show_error("Plot Load Failed", "Could not load plot metadata.", str(error))
+            return True
+        pending.add(request)
+        timer = QtCore.QTimer(self)
+        timer.setInterval(10)
+
+        def poll():
+            stale = (getattr(self, "_shutdown_started", False)
+                     or service is not getattr(self, "_trusted_read_service", None)
+                     or (selection is not None and selection != (
+                         getattr(self, "selected_run_id", None),
+                         getattr(self, "_selected_run_guid", None)))
+                     or not self._dataset_key_is_current(key))
+            if stale:
+                request.cancel()
+            if not stale and not request.done:
+                return
+            timer.stop()
+            timer.deleteLater()
+            pending.discard(request)
+            if stale:
+                return
+            try:
+                dataset = request.wait(0)
+                ready = self.__dict__.setdefault("_trusted_plot_ready", {})
+                ready[key] = dataset
+                try:
+                    resume()
+                finally:
+                    ready.pop(key, None)
+            except Exception as error:
+                log_exception("Trusted plot launch failed", error, __name__)
+                self.show_error("Plot Load Failed", "Could not load the selected run.", str(error))
+
+        timer.timeout.connect(poll)
+        timer.start()
+        self.show_status("Loading plot metadata...", 0)
+        return True
+
+    def _generation_gate_allows_action(self, database_path=None, operation=None):
+        gate = getattr(self, "_database_generation_read_allowed", None)
+        if not callable(gate):
+            return True
+        return gate(
+            database_path,
+            operation=operation or "using run data",
+        )
+
+    @staticmethod
+    def _dataset_key_is_current(dataset_key):
+        return dataset_key_matches_current_source(
+            dataset_key,
+            allow_new_sidecars=True,
+        )
+
+
+    @staticmethod
+    def _bound_plot_dataset_key_is_current(dataset_key):
+        """Require the exact source identities retained by a plot key."""
+
+        return dataset_key_matches_current_source(dataset_key)
+
+
+    def _request_plot_source_recovery(self, dataset_key):
+        """Retire a plot source without trusting the controller baseline."""
+
+        replacement_handler = getattr(
+            self,
+            "_handle_plot_database_replaced",
+            None,
+        )
+        if callable(replacement_handler):
+            replacement_handler(dataset_key.database_path)
+            return
+
+        reload_replaced = getattr(self, "_reload_replaced_database", None)
+        if callable(reload_replaced):
+            reload_replaced(dataset_key.database_path)
+
+
+    def _ensure_bound_plot_dataset_key_can_be_read(self, dataset_key):
+        """Reject a retained plot key unless every accepted identity matches."""
+
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                dataset_key.database_path,
+                "using run data",
+                ):
+            raise RuntimeError(
+                "Test-database generation owns this database path until its "
+                "released view has recovered."
+            )
+        if PlotActionsMixin._bound_plot_dataset_key_is_current(dataset_key):
+            return
+
+        PlotActionsMixin._request_plot_source_recovery(self, dataset_key)
+        raise RuntimeError(
+            "The database or its SQLite sidecars were replaced before the "
+            "plot could use its dataset."
+        )
+
+
+    def _rekey_dataset_handle_for_bound_plot(self, prior_key, bound_key):
+        """Replace an equal transient dict key with its exact plot binding."""
+
+        for held_key in list(self.dataset_holder):
+            if held_key != prior_key:
+                continue
+            handle = self.dataset_holder.pop(held_key)
+            held_sidecars = handle.sidecar_identities
+            if (
+                    held_sidecars is not None
+                    and not held_sidecars.issubset(bound_key.sidecar_identities)
+                    ):
+                # This handle came from a different exact sidecar lineage even
+                # though DatasetKey deliberately excludes sidecars from hash
+                # equality.  Do not let it satisfy the promoted plot key.
+                self.dataset_holder[held_key] = handle
+                return False
+            handle.sidecar_identities = bound_key.sidecar_identities
+            self.dataset_holder[bound_key] = handle
+            return True
+        return False
+
+
+    def _bind_plot_dataset_key(self, dataset_key):
+        """Finish first-sidecar binding before retaining a plot source."""
+
+        bound_key = bind_dataset_key_to_current_source(dataset_key)
+        if bound_key is None:
+            PlotActionsMixin._request_plot_source_recovery(self, dataset_key)
+            return None
+        PlotActionsMixin._rekey_dataset_handle_for_bound_plot(
+            self,
+            dataset_key,
+            bound_key,
+        )
+        try:
+            PlotActionsMixin._ensure_bound_plot_dataset_key_can_be_read(
+                self,
+                bound_key,
+            )
+        except RuntimeError:
+            return None
+        return bound_key
+
+
+    def _dataset_key_targets_loaded_database(self, dataset_key):
+        """Return whether a key names the database currently shown in the UI."""
+
+        file_textbox = getattr(self, "fileTextbox", None)
+        current_path = file_textbox.text() if file_textbox is not None else ""
+        return bool(
+            current_path
+            and logical_database_path(current_path) == dataset_key.database_path
+        )
+
+
+    def _ensure_dataset_key_can_be_read(self, dataset_key):
+        """Reject a plot read until an atomically replaced source is reloaded."""
+
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                dataset_key.database_path,
+                "using run data",
+                ):
+            raise RuntimeError(
+                "Test-database generation owns this database path until its "
+                "released view has recovered."
+            )
+
+        if self._dataset_key_targets_loaded_database(dataset_key):
+            reload_if_changed = getattr(
+                self,
+                "_reload_if_database_instance_changed",
+                None,
+            )
+            if callable(reload_if_changed) and reload_if_changed(
+                    dataset_key.database_path,
+                    ):
+                raise RuntimeError(
+                    "The database was replaced and is being reloaded before "
+                    "its dataset can be opened."
+                )
+
+        if not self._dataset_key_is_current(dataset_key):
+            raise RuntimeError(
+                "The database was replaced before its dataset could be loaded."
+            )
+
+
+    def _discard_dataset_handle(self, dataset_key, handle):
+        """Remove and close one handle that cannot represent its key safely."""
+        if self.dataset_holder.get(dataset_key) is handle:
+            self.dataset_holder.pop(dataset_key, None)
+        if handle.dataset is getattr(self, "ds", None):
+            self.ds = None
+            self._selected_dataset_key = None
+            self.selected_run_id = None
+        try:
+            handle.close()
+        except Exception as err:
+            log_exception("Stale plot dataset cleanup failed", err, __name__)
+
+
+    def _dataset_handle_for_key(self, dataset_key):
+        """Return only a handle opened for the key's current file instance."""
+        key_is_current = self._dataset_key_is_current(dataset_key)
+        if not key_is_current:
+            stale_handle = self.dataset_holder.get(dataset_key)
+            if stale_handle is not None:
+                self._discard_dataset_handle(dataset_key, stale_handle)
+            return None
+
+        for cached_key in list(self.dataset_holder):
+            if (
+                    cached_key != dataset_key
+                    and cached_key.database_path == dataset_key.database_path
+                    and cached_key.guid == dataset_key.guid
+                    ):
+                superseded = self.dataset_holder.get(cached_key)
+                if superseded is not None:
+                    self._discard_dataset_handle(cached_key, superseded)
+
+        handle = self.dataset_holder.get(dataset_key)
+        if handle is None:
+            return None
+        if (
+                handle.closed
+                or (
+                    handle.database_identity is not None
+                    and handle.database_identity != dataset_key.database_identity
+                )
+                or (
+                    handle.sidecar_identities is not None
+                    and handle.sidecar_identities
+                    != dataset_key.sidecar_identities
+                )
+                ):
+            self._discard_dataset_handle(dataset_key, handle)
+            return None
+        if handle.database_identity is None:
+            handle.database_identity = dataset_key.database_identity
+        if handle.sidecar_identities is None:
+            handle.sidecar_identities = dataset_key.sidecar_identities
+        return handle
+
+    def _dataset_is_held(self, dataset):
+        return dataset is not None and any(
+            handle.dataset is dataset
+            for handle in self.dataset_holder.values()
+            )
+
+
+    def _close_dataset_if_unowned(self, dataset, context="Dataset cleanup failed"):
+        if dataset is None or dataset is getattr(self, "ds", None):
+            return False
+        if self._dataset_is_held(dataset):
+            return False
+        try:
+            return close_dataset_connection(dataset)
+        except Exception as err:
+            log_exception(context, err, __name__)
+            return False
+
+
+    def _replace_selected_dataset(self, dataset, dataset_key):
+        previous = getattr(self, "ds", None)
+        self.ds = dataset
+        self._selected_dataset_key = dataset_key
+        self._selected_run_guid = dataset_key.guid
+        if previous is not dataset:
+            self._close_dataset_if_unowned(
+                previous,
+                context="Previous selected dataset cleanup failed",
+                )
+
+
+    def _release_selected_dataset(self):
+        previous = getattr(self, "ds", None)
+        self.ds = None
+        self._selected_dataset_key = None
+        return self._close_dataset_if_unowned(
+            previous,
+            context="Selected dataset cleanup failed",
+            )
+
+
+    def _release_trusted_action_dataset(self, dataset):
+        """End an explicit trusted-mode DataSet's GUI-thread ownership.
+
+        Stage 4 permits legacy DataSet materialisation only at an explicit plot
+        or export boundary.  A plot window retains its DataSet through
+        ``dataset_holder``; an unused or failed action must close its unowned
+        handle here so a later ordinary row selection has no SQLite cleanup to
+        perform.
+        """
+        if (
+                dataset is None
+                or getattr(self, "_database_access_mode", None)
+                != TRUSTED_LIVE_MODE
+                ):
+            return False
+        if getattr(self, "ds", None) is dataset:
+            self.ds = None
+            self._selected_dataset_key = None
+        return self._close_dataset_if_unowned(
+            dataset,
+            context="Explicit plot dataset cleanup failed",
+        )
+
+
+    def _clear_selected_run_state(self):
+        """Clear run actions and UI after a selected dataset cannot be loaded."""
+        cancel_detail = getattr(self, "_cancel_selected_run_detail", None)
+        if callable(cancel_detail):
+            cancel_detail()
+        self._release_selected_dataset()
+        self.selected_run_id = None
+        self._selected_run_guid = None
+
+        run_id_box = getattr(self, "run_idBox", None)
+        if run_id_box is not None:
+            signals_blocked = run_id_box.blockSignals(True)
+            try:
+                run_id_box.setText("")
+            finally:
+                run_id_box.blockSignals(signals_blocked)
+
+        run_list = getattr(self, "RunList", None)
+        if run_list is not None:
+            signals_blocked = run_list.blockSignals(True)
+            try:
+                run_list.clearSelection()
+                set_current_item = getattr(run_list, "setCurrentItem", None)
+                if callable(set_current_item):
+                    set_current_item(None)
+            finally:
+                run_list.blockSignals(signals_blocked)
+
+        info_box = getattr(self, "infoBox", None)
+        if info_box is not None:
+            info_box.clear()
+        derived_bridge = getattr(self, "_trusted_derived_bridge", None)
+        if derived_bridge is not None:
+            derived_bridge.select_run(None)
+
+
+    @QtCore.pyqtSlot()
+    def clear_non_single_run_selection(self):
+        """Drop the single-run action target for an empty or multi-selection."""
+        self._clear_selected_run_state()
+
+
+    def _evict_dataset_handle(self, dataset_key):
+        handle = self.dataset_holder.pop(dataset_key, None)
+        if handle is None:
+            return False
+
+        handle.cancel_delete_timer()
+        if handle.dataset is getattr(self, "ds", None):
+            return True
+        try:
+            handle.close()
+        except Exception as err:
+            log_exception("Plot dataset cleanup failed", err, __name__)
+        return True
+
+
+    def _close_all_dataset_handles(self):
+        handles = list(self.dataset_holder.values())
+        self.dataset_holder.clear()
+        for handle in handles:
+            try:
+                handle.close()
+            except Exception as err:
+                log_exception("Plot dataset cleanup failed", err, __name__)
+
+
+    @staticmethod
+    def _dataset_key_matches_replaced_instance(dataset_key, database_source):
+        """Match a key against saved old-instance information."""
+
+        if dataset_key is None:
+            return False
+        if isinstance(database_source, DatasetKey):
+            logical_path = database_source.database_path
+            resolved_path = database_source.resolved_database_path
+            identity = database_source.database_identity
+        elif isinstance(database_source, DatabaseInstance):
+            logical_path = database_source.logical_path
+            resolved_path = database_source.resolved_path
+            identity = database_source.identity
+        else:
+            return dataset_key.database_path == logical_database_path(database_source)
+
+        if dataset_key.database_path != logical_path:
+            return False
+        if identity is not None and dataset_key.database_identity is not None:
+            return dataset_key.database_identity == identity
+        return dataset_key.resolved_database_path == resolved_path
+
+
+    def _detach_replaced_secondary_traces(self, database_source):
+        """Remove secondary plots whose source belongs to a replaced database.
+
+        A merged source can be closed and therefore absent from ``windows``
+        while its layer still owns a dataset handle and keeps its monitor
+        alive. Retire those consumers before evicting the source handle so a
+        plot backed by another database cannot retain or refresh stale data.
+        """
+        def source_matches(dataset_key):
+            return self._dataset_key_matches_replaced_instance(
+                dataset_key,
+                database_source,
+            )
+
+        for host in list(getattr(self, "windows", [])):
+            host_key = getattr(host, "_dataset_key", None)
+            # Hosts from the replaced database are closed below, and their
+            # close event already detaches every secondary line.
+            if (
+                    host_key is not None
+                    and source_matches(host_key)
+                    ):
+                continue
+
+            for registry_name, main_item_name, remove_name in (
+                    ("lines", "line", "remove_line"),
+                    ("heatmaps", None, "remove_heatmap"),
+                    ):
+                registry = getattr(host, registry_name, None)
+                remover = getattr(host, remove_name, None)
+                if not isinstance(registry, dict) or not callable(remover):
+                    continue
+
+                main_item = host if main_item_name is None else getattr(
+                    host,
+                    main_item_name,
+                    None,
+                    )
+                stale_layers = [
+                    (trace_key, layer)
+                    for trace_key, layer in list(registry.items())
+                    if (
+                        layer is not None
+                        and layer is not main_item
+                        and getattr(
+                            getattr(layer, "from_win", None),
+                            "_dataset_key",
+                            None,
+                            ) is not None
+                        and source_matches(layer.from_win._dataset_key)
+                        )
+                    ]
+                for trace_key, layer in stale_layers:
+                    source = layer.from_win
+                    try:
+                        remover(
+                            getattr(source, "label", ""),
+                            trace_key=trace_key,
+                            )
+                    except Exception as err:
+                        log_exception(
+                            "Replaced database secondary-plot cleanup failed",
+                            err,
+                            __name__,
+                        )
+
+
+    def _invalidate_database_runtime_state(self, database_source):
+        """Close datasets and plot windows backed by a replaced database."""
+        self._detach_replaced_secondary_traces(database_source)
+        selected_key = getattr(self, "_selected_dataset_key", None)
+        if (
+                selected_key is not None
+                and self._dataset_key_matches_replaced_instance(
+                    selected_key,
+                    database_source,
+                )
+                ):
+            self._release_selected_dataset()
+            self.selected_run_id = None
+
+        for win in list(getattr(self, "windows", [])):
+            dataset_key = getattr(win, "_dataset_key", None)
+            if (
+                    dataset_key is None
+                    or not self._dataset_key_matches_replaced_instance(
+                        dataset_key,
+                        database_source,
+                    )
+                    ):
+                continue
+            try:
+                win.close()
+            except Exception as err:
+                log_exception("Replaced database plot cleanup failed", err, __name__)
+
+        for dataset_key in list(self.dataset_holder):
+            if self._dataset_key_matches_replaced_instance(
+                    dataset_key,
+                    database_source,
+                    ):
+                self._evict_dataset_handle(dataset_key)
+
+
+    def _handle_plot_database_replaced(self, database_path, source_window=None):
+        """Reload the current source, or retire a stale plot from another DB."""
+
+        file_textbox = getattr(self, "fileTextbox", None)
+        if file_textbox is None:
+            # Lightweight PlotActionsMixin hosts do not own MainWindow's path
+            # field.  Let their normal instance-change hook perform recovery
+            # instead of entering controller-specific invalidation code.
+            reload_if_changed = getattr(
+                self,
+                "_reload_if_database_instance_changed",
+                None,
+            )
+            if callable(reload_if_changed):
+                return reload_if_changed(database_path)
+            return False
+
+        current_path = file_textbox.text()
+        source_key = getattr(source_window, "_dataset_key", None)
+        logical_source_path = (
+            source_key.database_path
+            if source_key is not None
+            else logical_database_path(database_path)
+        )
+        if (
+                current_path
+                and logical_database_path(current_path) == logical_source_path
+                ):
+            return self._reload_replaced_database(current_path)
+
+        # qPlot may retain plots from a database that is no longer selected in
+        # MainWindow. A replacement there must not switch the main UI back to
+        # that path; discard only those stale runtime objects instead.
+        self._invalidate_database_runtime_state(source_key or database_path)
+        return False
+
+    @QtCore.pyqtSlot(object)
+    def onClose(self, win):
+        """
+        Event handler for closing a Plot window.
+
+        """
+        self.windows.remove(win)
+        self.remove_ds_at(win._dataset_key)
+        self.post_admin()
+        self.show_status(f"Closed {win.label}", 3000)
+        del win
+
+
+    def _publish_displayed_plot_preview(self, plot, worker):
+        """Show one displayed measurement while run previews are queued."""
+
+        preview = getattr(getattr(self, "infoBox", None), "preview", None)
+        if preview is None or getattr(preview, "_shutting_down", False):
+            return
+        key = getattr(plot, "_dataset_key", None)
+        if not isinstance(key, DatasetKey) or key.guid not in preview.run_metadata:
+            return
+        if getattr(worker, "dataset_completed", None) is not True:
+            # For an active run, reuse only the same row prefix currently
+            # advertised by the run list. Its next metadata update will
+            # discard the provisional image and request fresh derived work.
+            try:
+                displayed_count = int(worker.dataset_length_at_start)
+                listed_count = int(
+                    preview.run_metadata[key.guid]["result_count"]
+                )
+            except (AttributeError, KeyError, TypeError, ValueError):
+                return
+            if displayed_count != listed_count:
+                return
+        if not dataset_key_matches_current_source(key):
+            return
+        if getattr(preview, "_trusted_derived_mode", False):
+            bridge = getattr(self, "_trusted_derived_bridge", None)
+            instance = getattr(bridge, "_database_instance", None)
+            if not getattr(bridge, "_accepting_publications", False):
+                return
+        else:
+            instance = getattr(preview, "database_instance", None)
+        if (
+            instance is None
+            or instance.logical_path != key.database_path
+            or instance.resolved_path != key.resolved_database_path
+            or instance.identity != key.database_identity
+        ):
+            return
+        preview_generation = preview.generation
+
+        from ._widgets.preview import render_displayed_plot_preview
+
+        plot_preview = render_displayed_plot_preview(
+            worker,
+            getattr(plot, "param", None),
+            preview.preview_size,
+        )
+        if (
+            plot_preview is None
+            or preview.generation != preview_generation
+            or not dataset_key_matches_current_source(key)
+        ):
+            return
+        if getattr(preview, "_trusted_derived_mode", False):
+            bridge = getattr(self, "_trusted_derived_bridge", None)
+            if (
+                not getattr(bridge, "_accepting_publications", False)
+                or getattr(bridge, "_database_instance", None) != instance
+            ):
+                return
+        elif preview.database_instance != instance:
+            return
+        preview.publish_plot_preview(key.guid, plot_preview)
+
+    @QtCore.pyqtSlot(object, object, tuple)
+    def openWin(
+            self,
+            widget,
+            key_or_ds,
+            *args,
+            show=True,
+            dataset_key: DatasetKey | None = None,
+            **kargs,
+            ):
+        """
+        Handles opening Plot window, widget.
+
+        """
+        if len(args) == 1 and isinstance(args[0], (tuple, list)):
+            args = tuple(args[0])
+
+        if isinstance(key_or_ds, DatasetKey):
+            ds = None
+            if dataset_key is not None and dataset_key != key_or_ds:
+                raise ValueError("Conflicting dataset keys supplied while opening a plot.")
+            dataset_key = key_or_ds
+        else:
+            ds = key_or_ds
+            if dataset_key is None:
+                dataset_key = self._current_dataset_key(ds.guid)
+
+        assert dataset_key is not None
+        self._ensure_bound_plot_dataset_key_can_be_read(dataset_key)
+        shared_handle = self._dataset_handle_for_key(dataset_key)
+        loaded_for_construction = shared_handle is None and ds is None
+        if shared_handle is not None:
+            construction_ds = shared_handle.dataset
+        elif loaded_for_construction:
+            construction_ds = self._load_dataset(dataset_key)
+        else:
+            construction_ds = ds
+
+        assert construction_ds.guid == dataset_key.guid
+        construction_holder = {
+            held_key: DatasetHandle(
+                dataset=handle.dataset,
+                users=handle.users,
+                database_identity=handle.database_identity,
+                sidecar_identities=handle.sidecar_identities,
+            )
+            for held_key, handle in self.dataset_holder.items()
+        }
+        construction_holder[dataset_key] = DatasetHandle(
+            dataset=construction_ds,
+            database_identity=dataset_key.database_identity,
+            sidecar_identities=dataset_key.sidecar_identities,
+        )
+
+        try:
+            win = widget(
+                dataset_key,
+                *args,
+                self.config,
+                self.threadPool,
+                construction_holder,
+                show=show,
+                **kargs,
+            )
+            window_type = getattr(win, "operation_kind", None)
+            if window_type is None:
+                legacy_window_type = win.__class__.__name__
+                if legacy_window_type in {"plot1d", "plot2d", "sweeper"}:
+                    window_type = legacy_window_type
+            if window_type not in {"plot1d", "plot2d", "sweeper"}:
+                raise TypeError(f"Unknown window of type: {win.__class__.__name__}")
+            self._ensure_bound_plot_dataset_key_can_be_read(dataset_key)
+        except Exception:
+            if "win" in locals():
+                worker = getattr(win, "worker", None)
+                cancel = getattr(worker, "cancel", None)
+                if callable(cancel):
+                    cancel()
+                close = getattr(win, "close", None)
+                if callable(close):
+                    close()
+            if loaded_for_construction:
+                try:
+                    close_dataset_connection(construction_ds)
+                except Exception as err:
+                    log_exception("Unused plot dataset cleanup failed", err, __name__)
+            raise
+
+        win._dataset_holder = self.dataset_holder
+        self.add_ds_at(dataset_key, ds=construction_ds)
+
+        self.windows.append(win)
+        win._plot_preview_sink = self._publish_displayed_plot_preview
+
+        win.closed.connect(self.onClose)
+        database_replaced = getattr(win, "database_replaced", None)
+        connect_replacement = getattr(database_replaced, "connect", None)
+        if callable(connect_replacement):
+            connect_replacement(
+                lambda database_path, source_window=win: (
+                    self._handle_plot_database_replaced(
+                        database_path,
+                        source_window,
+                    )
+                )
+            )
+        win.make_ds.connect(self.add_ds_at)
+        win.previewTraceDropRequested.connect(self.add_dropped_preview_to_plot)
+        if window_type == "plot1d":
+            win.get_mergables.connect(lambda: self.get_1d_wins(win))
+            win.remove_dataset.connect(self.remove_ds_at)
+            win._trace_candidate_provider = (
+                lambda target_window=win: self._trace_candidates_for_plot(target_window)
+            )
+            win._trace_add_request = (
+                lambda source_key, parameter_name, target_window=win:
+                self.add_trace_to_plot(target_window, source_key, parameter_name)
+            )
+
+        elif window_type == "plot2d":
+            win.open_subplot.connect(self.openWin)
+            win.close_sweeps_requested.connect(self.close_sweeps_from_plot)
+            win._heatmap_candidate_provider = (
+                lambda target_window=win: self._heatmap_candidates_for_plot(
+                    target_window
+                )
+            )
+            win._heatmap_add_request = (
+                lambda source_key, parameter_name, target_window=win:
+                self.add_heatmap_to_plot(
+                    target_window,
+                    source_key,
+                    parameter_name,
+                )
+            )
+            remove_dataset = getattr(win, "remove_dataset", None)
+            if remove_dataset is not None:
+                remove_dataset.connect(self.remove_ds_at)
+
+        elif window_type == "sweeper":
+            win.merge_compatibility_changed.connect(self.post_admin)
+            for item in self.windows:
+                if item.ds == win.ds and item.param == win.param and isinstance(item, plot2d):
+                    win.sweep_moved.connect(item.update_sweep_line)
+                    win.remove_sweep.connect(item.remove_sweep)
+                    item.sweep_moved.connect(win.update_sweep_line)
+                    break
+            self.post_admin()
+
+        if show:
+            win.update_theme(self.config)
+
+            win.move(self._next_plot_x, self._next_plot_y)
+            win.show()
+
+            tolerance = 30
+            plot_width = win.width()
+            plot_height = win.height()
+            self._next_plot_x += plot_width
+            if self._next_plot_x + plot_width - tolerance > self.screenrect.right():
+                self._next_plot_x = self.screenrect.left()
+                self._next_plot_y += plot_height
+
+                if self._next_plot_y + plot_height - tolerance > self.screenrect.bottom():
+                    self._next_plot_y = self.screenrect.top()
+
+
+    @QtCore.pyqtSlot(object, object)
+    def close_sweeps_from_plot(self, source_win, sweep_ids):
+        """
+        Close cut windows associated with a heatmap cut-line action.
+
+        """
+        target_ids = set(sweep_ids)
+        if not target_ids:
+            return
+
+        for item in list(self.windows):
+            window_type = getattr(item, "operation_kind", item.__class__.__name__)
+            if window_type != "sweeper":
+                continue
+
+            try:
+                same_source = item.ds == source_win.ds and item.param == source_win.param
+                should_close = same_source and item.sweep_id in target_ids
+            except (AttributeError, RuntimeError):
+                continue
+
+            if should_close:
+                item.close()
+
+
+    @QtCore.pyqtSlot(str)
+    def updateSelected(self, guid):
+        """
+        Dispatch ordinary selection to one accepted, DataSet-free reader.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="selecting a run",
+                ):
+            return
+        if getattr(self, "_database_access_mode", None) == TRUSTED_LIVE_MODE:
+            update_trusted = getattr(self, "_update_trusted_selected_run", None)
+            if callable(update_trusted):
+                update_trusted(guid)
+            else:
+                self.show_error(
+                    "Trusted Selection Unavailable",
+                    "The accepted trusted live-reader selection path is unavailable.",
+                    "Reload the database to start a new trusted session. qPlot did "
+                    "not fall back to loading a snapshot DataSet.",
+                )
+            return
+        if (
+                getattr(self, "_database_access_mode", None)
+                == SNAPSHOT_FALLBACK_MODE
+                ):
+            update_snapshot = getattr(self, "_update_snapshot_selected_run", None)
+            if callable(update_snapshot):
+                update_snapshot(guid)
+            else:
+                self.show_error(
+                    "Snapshot Selection Unavailable",
+                    "The accepted snapshot selection path is unavailable.",
+                    "Reload the database to start a new snapshot session. qPlot "
+                    "did not load a QCoDeS DataSet for ordinary selection.",
+                )
+            return
+        self.show_error(
+            "Selection Unavailable",
+            "No accepted database reader is bound to the current selection.",
+            "Reload the database to establish a trusted live or snapshot "
+            "session. qPlot did not load a QCoDeS DataSet.",
+        )
+
+
+    def _run_metadata_for_guid(self, guid):
+        run_list = getattr(self, "RunList", None)
+        if run_list is None or not hasattr(run_list, "_item_for_guid"):
+            return {}
+
+        item = run_list._item_for_guid(guid)
+        if item is None:
+            return {}
+        return dict(getattr(item, "run_metadata", {}) or {})
+
+
+    def _run_point_count(self, metadata):
+        for key in ("result_count", "setpoint_count", "expected_results"):
+            value = metadata.get(key)
+            if value is None:
+                continue
+            try:
+                return int(value)
+            except (TypeError, ValueError):
+                continue
+        return None
+
+
+    @QtCore.pyqtSlot()
+    @_trusted_plot_action
+    def openRun(self):
+        """
+        Plots the requested measurement for the requested run.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="opening a plot",
+                ):
+            return
+        ds = self._dataset_for_plot_target()
+        if ds is None:
+            return
+
+        try:
+            params = self._selected_measurement_params(ds)
+        except Exception as error:
+            log_exception("Run parameter enumeration failed", error, __name__)
+            self._close_dataset_if_unowned(ds)
+            self.show_error(
+                "Run Load Failed",
+                "Could not read the selected run's measurements.",
+                str(error),
+                )
+            return
+        if params is None:
+            self._close_dataset_if_unowned(ds)
+            return
+
+        dataset_key = self._accepted_plot_target_key(ds)
+        if dataset_key is None:
+            self._close_dataset_if_unowned(ds)
+            return
+        self._replace_selected_dataset(ds, dataset_key)
+        try:
+            self.openPlot(params=params)
+        finally:
+            self._release_trusted_action_dataset(ds)
+
+
+    @QtCore.pyqtSlot()
+    @_trusted_plot_action
+    def open_selected_run_all(self):
+        """
+        Opens every plottable measurement in the currently selected table row.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="opening plots",
+                ):
+            return
+        guid = getattr(self, "_selected_run_guid", None)
+        if self.ds is None and not guid:
+            self.show_status("Select a run before plotting all measurements.", 5000)
+            return
+
+        self.openPlot(guid)
+
+
+    @QtCore.pyqtSlot()
+    def exportRunCsv(self):
+        """
+        Exports the requested run and measurement data to a CSV file.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="exporting run data",
+                ):
+            return
+        request = self._run_csv_export_request()
+        if request is None:
+            return
+        dataset_key, parameter_names, run_id = request
+        self._export_measurement_csv(
+            dataset_key,
+            parameter_names,
+            run_id=run_id,
+        )
+
+
+    @QtCore.pyqtSlot(str)
+    def export_preview_csv(self, parameter_name):
+        """
+        Exports the measurement represented by a selected-run preview image.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="exporting preview data",
+                ):
+            return
+        guid = getattr(self, "_selected_run_guid", None)
+        if self.ds is None and not guid:
+            self.show_status("Select a run before exporting a preview.", 5000)
+            return
+
+        dataset_key = getattr(self, "_selected_dataset_key", None)
+        if dataset_key is None:
+            dataset_key = self._current_dataset_key(guid or self.ds.guid)
+        self._export_preview_csv(dataset_key, parameter_name)
+
+
+    @QtCore.pyqtSlot(str, str)
+    def export_run_preview_csv(self, guid, parameter_name):
+        """
+        Exports the measurement represented by a run-table preview image.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="exporting preview data",
+                ):
+            return
+        if not guid:
+            self.show_status("Select a run before exporting a preview.", 5000)
+            return
+
+        self._export_preview_csv(self._current_dataset_key(guid), parameter_name)
+
+
+    def _export_preview_csv(self, dataset_key, parameter_name):
+        """Export one preview through a fresh, action-owned dataset view."""
+        default_name = self._default_preview_export_filename(
+            dataset_key,
+            parameter_name,
+        )
+        filename = self._choose_csv_export_filename(default_name)
+        if filename is None:
+            return
+
+        dataset = None
+        original_dataset_key = dataset_key
+        try:
+            # Preview and plot datasets intentionally remain frozen at their
+            # original read-only WAL snapshots.  Export needs the newest
+            # committed rows, so choose the destination first and only then
+            # bypass DatasetHandle caching.  No action-owned snapshot waits
+            # behind the modal save dialog.
+            try:
+                dataset_key = self._bind_one_shot_dataset_key(dataset_key)
+                dataset = self._load_run_csv_dataset(dataset_key)
+                param = self._measurement_param_by_name(dataset, parameter_name)
+            except DatabaseInstanceChangedError as err:
+                self._handle_run_csv_source_replaced(
+                    dataset_key or original_dataset_key,
+                )
+                log_exception("Preview CSV run load failed", err, __name__)
+                self.show_error(
+                    "Run Load Failed",
+                    f"Could not load run with GUID {original_dataset_key.guid}.",
+                    str(err),
+                )
+                return
+            except Exception as err:
+                log_exception("Preview CSV run load failed", err, __name__)
+                self.show_error(
+                    "Run Load Failed",
+                    f"Could not load run with GUID {dataset_key.guid}.",
+                    str(err),
+                )
+                return
+
+            if param is None:
+                self.show_status(
+                    f"No preview export found for {parameter_name}.",
+                    5000,
+                )
+                return
+
+            try:
+                frame = self._measurement_dataframe(dataset, [param])
+                # The read-only connection intentionally keeps its original
+                # SQLite snapshot readable if the path is replaced.  Reject
+                # that obsolete frame before it reaches the destination.
+                self._require_run_csv_source_current(dataset_key)
+                self._publish_preview_csv(frame, filename, dataset_key)
+            except DatabaseInstanceChangedError as err:
+                self._handle_run_csv_source_replaced(dataset_key)
+                log_exception("Preview CSV export failed", err, __name__)
+                self.show_error(
+                    "CSV Export Failed",
+                    "Could not export the selected measurement data.",
+                    str(err),
+                )
+                return
+            except Exception as err:
+                log_exception("Preview CSV export failed", err, __name__)
+                self.show_error(
+                    "CSV Export Failed",
+                    "Could not export the selected measurement data.",
+                    str(err),
+                )
+                return
+
+            self.show_status(f"Exported CSV: {filename}", 5000)
+        finally:
+            if dataset is not None:
+                try:
+                    close_dataset_connection(dataset)
+                except Exception as err:
+                    log_exception(
+                        "Preview CSV dataset cleanup failed",
+                        err,
+                        __name__,
+                    )
+
+
+    def _export_measurement_csv(
+            self,
+            dataset_key,
+            parameter_names,
+            *,
+            run_id=None,
+            ):
+        """Export a captured run request through a fresh read-only dataset."""
+        parameter_names = tuple(str(name) for name in parameter_names)
+        if not parameter_names:
+            self.show_status("No plottable measurements to export for this run.", 5000)
+            return
+
+        default_name = self._default_run_csv_export_filename(
+            dataset_key,
+            parameter_names,
+            run_id=run_id,
+        )
+        filename = self._choose_csv_export_filename(default_name)
+        if filename is None:
+            return
+
+        dataset = None
+        original_dataset_key = dataset_key
+        try:
+            # The destination is approved before this action-owned view is
+            # opened, so a modal save dialog cannot retain an obsolete SQLite
+            # snapshot. The read layer also binds acquisition to the database
+            # identity captured in ``dataset_key``.
+            dataset_key = self._bind_one_shot_dataset_key(dataset_key)
+            dataset = self._load_run_csv_dataset(dataset_key)
+            params = self._measurement_params_by_names(dataset, parameter_names)
+            frame = self._measurement_dataframe(dataset, params)
+            self._require_run_csv_source_current(dataset_key)
+            write_export_atomically(
+                filename,
+                lambda temporary: frame.to_csv(temporary, index=False),
+                before_publish=(
+                    lambda: self._require_run_csv_source_current(dataset_key)
+                ),
+            )
+        except DatabaseInstanceChangedError:
+            self._handle_run_csv_source_replaced(
+                dataset_key or original_dataset_key,
+            )
+            return
+        except Exception as err:
+            log_exception("CSV export failed", err, __name__)
+            self.show_error(
+                "CSV Export Failed",
+                "Could not export the selected measurement data.",
+                str(err),
+            )
+            return
+        finally:
+            if dataset is not None:
+                try:
+                    close_dataset_connection(dataset)
+                except Exception as err:
+                    log_exception("CSV dataset cleanup failed", err, __name__)
+
+        self.show_status(f"Exported CSV: {filename}", 5000)
+
+
+    def _load_run_csv_dataset(self, dataset_key):
+        """Fresh-load one export view for an exact database instance."""
+        self._require_run_csv_source_current(dataset_key)
+        load_kwargs = {}
+        if dataset_key.database_identity is not None:
+            load_kwargs["expected_database_identity"] = (
+                dataset_key.database_identity
+            )
+        dataset = load_by_guid_read_only(
+            dataset_key.guid,
+            dataset_key.database_path,
+            **load_kwargs,
+        )
+        try:
+            self._require_run_csv_source_current(dataset_key)
+        except Exception:
+            try:
+                close_dataset_connection(dataset)
+            finally:
+                raise
+        return dataset
+
+
+    def _bind_one_shot_dataset_key(self, dataset_key):
+        """Bind compatible first sidecars before an action-owned read."""
+
+        bound_key = bind_dataset_key_to_current_source(dataset_key)
+        if bound_key is None:
+            raise DatabaseInstanceChangedError(
+                "The database or its SQLite sidecars were replaced before qPlot "
+                "could open the export view."
+            )
+        return bound_key
+
+
+    def _require_run_csv_source_current(self, dataset_key):
+        """Reject an export when its captured database instance was replaced."""
+        if not self._bound_plot_dataset_key_is_current(dataset_key):
+            raise DatabaseInstanceChangedError(
+                "The database or its SQLite sidecars were replaced while "
+                "qPlot was exporting run data."
+            )
+
+
+    def _handle_run_csv_source_replaced(self, dataset_key):
+        """Request replacement recovery without reporting a generic CSV error."""
+        reload_if_changed = getattr(
+            self,
+            "_reload_if_database_instance_changed",
+            None,
+        )
+        if callable(reload_if_changed):
+            reload_if_changed(dataset_key.database_path)
+        self.show_status(
+            "CSV export stopped because the database was replaced; "
+            "reloading the source. No CSV was written.",
+            5000,
+        )
+
+
+    def _choose_csv_export_filename(self, default_name):
+        try:
+            destination = choose_export_path(
+                self,
+                caption="Export CSV",
+                suggested_path=default_name,
+                name_filter="CSV files (*.csv)",
+                required_suffix=".csv",
+                replace_title="Replace CSV File?",
+                file_description="CSV file",
+            )
+        except Exception as err:
+            log_exception("CSV export destination rejected", err, __name__)
+            self.show_error(
+                "CSV Export Failed",
+                "qPlot could not safely use the selected CSV destination.",
+                str(err),
+            )
+            return None
+        if destination is None:
+            self.show_status("CSV export cancelled.", 3000)
+            return None
+        return destination
+
+
+    def _publish_preview_csv(self, frame, filename, dataset_key):
+        """Stage a preview CSV and publish it only for the requested source."""
+        # The source must still be the captured database instance immediately
+        # before the staged file atomically replaces the requested destination.
+        write_export_atomically(
+            filename,
+            lambda temporary: frame.to_csv(temporary, index=False),
+            before_publish=(
+                lambda: self._require_run_csv_source_current(dataset_key)
+            ),
+        )
+
+
+    @QtCore.pyqtSlot(str)
+    @_trusted_plot_action
+    def openPlot(self, guid: str | DatasetKey = None, params: list = None, show: bool = True):
+        """
+        Opens plot windows for the selected or requested run.
+
+        """
+        retained_dataset_key = isinstance(guid, DatasetKey)
+        target_path = guid.database_path if retained_dataset_key else None
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                target_path,
+                "opening plots",
+                ):
+            return
+
+        # ``DataSet`` implements truthiness through ``__len__``, which queries
+        # its SQLite connection.  A Windows replacement test (and a real
+        # replacement race) may have deliberately released that old read-only
+        # connection before this requested DatasetKey is invalidated.  Presence
+        # of a selected dataset is the relevant check here, not its row count.
+        selected_guid = getattr(self, "_selected_run_guid", None)
+        if self.ds is None and not guid and not selected_guid:
+            self.show_status("Select a run before opening plots.", 5000)
+            return
+
+        self.show_status("Opening plots...", 0)
+
+        if isinstance(guid, DatasetKey):
+            dataset_key = guid
+            guid = dataset_key.guid
+        else:
+            target_guid = guid or selected_guid or getattr(self.ds, "guid", "")
+            dataset_key = self._current_dataset_key(target_guid)
+
+        loaded_by_open_plot = False
+        try:
+            if retained_dataset_key:
+                self._ensure_bound_plot_dataset_key_can_be_read(dataset_key)
+            else:
+                self._ensure_dataset_key_can_be_read(dataset_key)
+            if (
+                self.ds is None
+                or getattr(self, "_selected_dataset_key", None) != dataset_key
+            ):
+                handle = self._dataset_handle_for_key(dataset_key)
+                if handle is None:
+                    ds = self._load_dataset(dataset_key)
+                    loaded_by_open_plot = True
+                else:
+                    ds = handle.dataset
+            else:
+                ds = self.ds
+
+            prior_key = dataset_key
+            if retained_dataset_key:
+                self._ensure_bound_plot_dataset_key_can_be_read(dataset_key)
+            else:
+                dataset_key = self._bind_plot_dataset_key(dataset_key)
+                if dataset_key is None:
+                    raise RuntimeError(
+                        "The database or its SQLite sidecars changed while "
+                        "the plot dataset was being acquired."
+                    )
+                if (
+                        self.ds is ds
+                        and getattr(self, "_selected_dataset_key", None)
+                        == prior_key
+                        ):
+                    self._selected_dataset_key = dataset_key
+                self._plot_target_dataset_key = dataset_key
+        except Exception as err:
+            if loaded_by_open_plot and "ds" in locals():
+                self._close_dataset_if_unowned(
+                    ds,
+                    context="Unused plot dataset cleanup failed",
+                )
+            log_exception("Plot run load failed", err, __name__)
+            self.show_error("Run Load Failed", "Could not load the selected run.", str(err))
+            return
+
+        opened = 0
+        skipped = 0
+        unsupported = []
+        try:
+            if not params:
+                params = ds.get_parameters()
+
+            for param in params:
+                if param.depends_on == "":
+                    continue
+
+                depends_on = param.depends_on_
+                if len(depends_on) > MAX_SUPPORTED_PLOT_DIMENSIONS:
+                    unsupported.append(
+                        unsupported_plot_message(param.name, depends_on)
+                        )
+                    continue
+                skip = False
+
+                if len(depends_on) == 1:
+                    for win in self.windows:
+                        if (
+                            win._dataset_key == dataset_key
+                            and win.param == param
+                            and isinstance(win, plot1d)
+                        ):
+                            skipped += 1
+                            skip = True
+                            break
+                    if skip:
+                        continue
+
+                    self.openWin(
+                        plot1d,
+                        ds,
+                        param,
+                        refrate=refresh_interval_value(self.spinBox),
+                        show=show,
+                        dataset_key=dataset_key,
+                    )
+                    opened += 1
+
+                else:
+                    for win in self.windows:
+                        if (
+                            win._dataset_key == dataset_key
+                            and win.param == param
+                            and isinstance(win, plot2d)
+                        ):
+                            skipped += 1
+                            skip = True
+                            break
+                    if skip:
+                        continue
+
+                    self.openWin(
+                        plot2d,
+                        ds,
+                        param,
+                        refrate=refresh_interval_value(self.spinBox),
+                        show=show,
+                        dataset_key=dataset_key,
+                    )
+                    opened += 1
+
+            self.post_admin()
+
+            if opened and show:
+                preview = getattr(getattr(self, "infoBox", None), "preview", None)
+                request_previews = getattr(preview, "request_guids", None)
+                if callable(request_previews):
+                    request_previews([dataset_key.guid])
+
+            if opened:
+                noun = "plot" if opened == 1 else "plots"
+                message = f"Opened {opened} {noun}."
+                if unsupported:
+                    message += f" Skipped {len(unsupported)} unsupported measurement(s)."
+                self.show_status(message, 8000 if unsupported else 5000)
+            elif skipped:
+                self.show_status("Selected plot windows are already open.", 5000)
+            elif unsupported:
+                self.show_status(unsupported[0], 10_000)
+            else:
+                self.show_status("No plottable parameters found for this run.", 5000)
+
+        except Exception as err:
+            log_exception("Plot open failed", err, __name__)
+            self.show_error("Plot Open Failed", "Could not open plot windows.", str(err))
+        finally:
+            dataset_is_held = dataset_key in self.dataset_holder or any(
+                handle.dataset is ds for handle in self.dataset_holder.values()
+            )
+            if loaded_by_open_plot and self.ds is not ds and not dataset_is_held:
+                self._close_dataset_if_unowned(
+                    ds,
+                    context="Unused plot dataset cleanup failed",
+                    )
+
+
+    @_trusted_plot_action
+    def open_param_by_index(self, index: int):
+        """
+        Open the indexed dependent parameter for the selected run.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="opening a plot",
+                ):
+            return
+        if self.ds is None:
+            dataset = self._dataset_for_plot_target()
+            if dataset is None:
+                return
+            dataset_key = self._accepted_plot_target_key(dataset)
+            if dataset_key is None:
+                self._close_dataset_if_unowned(dataset)
+                return
+            self._replace_selected_dataset(
+                dataset,
+                dataset_key,
+            )
+        action_dataset = self.ds
+        try:
+            params = [
+                param
+                for param in action_dataset.get_parameters()
+                if param.depends_on != ""
+            ]
+            if index >= len(params):
+                self.show_status(f"Run has no parameter {index + 1}.", 5000)
+                return
+
+            self.openPlot(params=[params[index]])
+        finally:
+            self._release_trusted_action_dataset(action_dataset)
+
+
+    @QtCore.pyqtSlot(str)
+    @_trusted_plot_action
+    def open_preview_plot(self, parameter_name):
+        """
+        Open the plot represented by a double-clicked preview image.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="opening a preview plot",
+                ):
+            return
+        if self.ds is None:
+            dataset = self._dataset_for_plot_target()
+            if dataset is None:
+                return
+            dataset_key = self._accepted_plot_target_key(dataset)
+            if dataset_key is None:
+                self._close_dataset_if_unowned(dataset)
+                return
+            self._replace_selected_dataset(
+                dataset,
+                dataset_key,
+            )
+        action_dataset = self.ds
+        try:
+            for param in action_dataset.get_parameters():
+                if param.name == parameter_name and param.depends_on != "":
+                    self.openPlot(params=[param])
+                    return
+
+            self.show_status(f"No preview plot found for {parameter_name}.", 5000)
+        finally:
+            self._release_trusted_action_dataset(action_dataset)
+
+
+    def open_selected_measurement(self, parameter_name):
+        """Materialise the selected run only after an explicit menu action."""
+        return self.open_preview_plot(str(parameter_name))
+
+
+    @QtCore.pyqtSlot(str, str)
+    @_trusted_plot_action
+    def open_run_preview_plot(self, guid, parameter_name):
+        """
+        Open the plot represented by a double-clicked run-table preview image.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="opening a preview plot",
+                ):
+            return
+        if not guid:
+            self.show_status("Select a run before opening a preview plot.", 5000)
+            return
+
+        dataset_key = self._current_dataset_key(guid)
+        if (
+            self.ds is None
+            or getattr(self, "_selected_dataset_key", None) != dataset_key
+        ):
+            try:
+                handle = self._dataset_handle_for_key(dataset_key)
+                if handle is None:
+                    dataset = self._load_dataset(dataset_key)
+                else:
+                    dataset = handle.dataset
+                self._replace_selected_dataset(dataset, dataset_key)
+            except Exception as err:
+                log_exception("Preview plot run load failed", err, __name__)
+                self.show_error("Run Load Failed", f"Could not load run with GUID {guid}.", str(err))
+                return
+
+        self.open_preview_plot(parameter_name)
+
+
+    @QtCore.pyqtSlot(object, object, str)
+    def add_dropped_preview_to_plot(self, target_win, source_identity, parameter_name):
+        """
+        Add a run-table preview to the plot it was dropped onto.
+
+        """
+        # The plot is normally in front of the main window when a drop occurs.
+        # Keep its status bar in sync with the main-window feedback produced by
+        # ``add_trace_to_plot`` so a post-drop rejection is visible where the
+        # user performed the action.
+        previous_target = getattr(self, "_preview_drop_feedback_window", None)
+        self._preview_drop_feedback_window = target_win
+        try:
+            return self.add_trace_to_plot(
+                target_win,
+                source_identity,
+                parameter_name,
+            )
+        finally:
+            self._preview_drop_feedback_window = previous_target
+
+
+    @_trusted_plot_action
+    def add_trace_to_plot(self, target_win, source_identity, parameter_name, param=None):
+        """
+        Add a compatible parameter to an existing plot.
+
+        The historical method name remains the entry point used by run-table
+        menus and preview drops. Heatmap targets dispatch to the corresponding
+        layer workflow; line targets retain the existing secondary-trace path.
+
+        """
+        if getattr(target_win, "operation_kind", None) == "plot2d":
+            return self.add_heatmap_to_plot(
+                target_win,
+                source_identity,
+                parameter_name,
+                param=param,
+                )
+
+        source_path = (
+            source_identity.database_path
+            if isinstance(source_identity, DatasetKey)
+            else None
+        )
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                source_path,
+                "adding a preview trace",
+                ):
+            return False
+        if target_win is None or not hasattr(target_win, "option_boxes"):
+            self.show_status("Drop traces onto a compatible line plot.", 5000)
+            return False
+
+        if isinstance(source_identity, DatasetKey):
+            source_key = source_identity
+        else:
+            source_key = self._current_dataset_key(source_identity)
+        source_guid = source_key.guid
+        if param is None:
+            try:
+                param = self._parameter_from_key(source_key, parameter_name)
+            except Exception as err:
+                log_exception("Trace source run load failed", err, __name__)
+                self.show_error(
+                    "Run Load Failed",
+                    f"Could not load run with GUID {source_guid}.",
+                    str(err),
+                )
+                return False
+
+        if param is None or not getattr(param, "depends_on", ""):
+            self.show_status(f"No preview plot found for {parameter_name}.", 5000)
+            return False
+
+        if len(getattr(param, "depends_on_", ())) != 1:
+            self.show_status("Only 1D measurements can be added as traces.", 5000)
+            return False
+
+        if tuple(param.depends_on_) != tuple(target_win.param.depends_on_):
+            self.show_status(
+                f"Cannot add {parameter_name}; the plot axes do not match.",
+                5000,
+            )
+            return False
+
+        from_win = self._plot_window_for_param(source_key, param)
+        if from_win == target_win:
+            self.show_status(f"Skipped {target_win.label}; source and target are the same.", 5000)
+            return False
+
+        if from_win is None:
+            from_win = self._open_hidden_trace_window(source_key, param, target_win)
+            if from_win is None:
+                return False
+
+        self.get_1d_wins(target_win)
+        if target_win.option_boxes[-1].isEnabled():
+            box = target_win.option_boxes[-1]
+        else:
+            target_win.add_option_box()
+            box = target_win.option_boxes[-1]
+
+        source_trace_key = getattr(from_win, "_trace_key", from_win.label)
+        index = _combo_index_for_data(box.option_box, source_trace_key)
+        if index < 0:
+            index = box.option_box.findText(from_win.label)
+        if index < 0:
+            self.show_status(
+                f"Cannot add {parameter_name}; it is already shown or incompatible.",
+                5000,
+            )
+            if not from_win.visible:
+                from_win.close()
+            return False
+
+        box.option_box.setCurrentIndex(index)
+        if not getattr(from_win, "visible", False):
+            from_win.close()
+        return True
+
+
+    def _trace_candidates_for_plot(self, target_win):
+        """Return loaded-database 1D measurements compatible with a plot."""
+
+        target_axes = tuple(
+            getattr(getattr(target_win, "param", None), "depends_on_", ())
+        )
+        if len(target_axes) != 1:
+            return []
+
+        run_list = getattr(self, "RunList", None)
+        all_run_metadata = getattr(run_list, "all_run_metadata", None)
+        if not callable(all_run_metadata):
+            return []
+
+        candidates = []
+        primary_trace_key = TraceKey(target_win._dataset_key, target_win.param.name)
+        for run_id, metadata in all_run_metadata().items():
+            if tuple(metadata.get("sweep_parameters") or ()) != target_axes:
+                continue
+            guid = metadata.get("guid")
+            if not guid:
+                continue
+            source_key = self._current_dataset_key(guid)
+            for parameter_name in metadata.get("measure_parameters") or ():
+                trace_key = TraceKey(source_key, parameter_name)
+                if (
+                    trace_key == primary_trace_key
+                    or trace_key in getattr(target_win, "lines", {})
+                ):
+                    continue
+                candidates.append((f"ID:{run_id} {parameter_name}", trace_key))
+        return candidates
+
+
+    def _heatmap_candidates_for_plot(self, target_win):
+        """Return loaded-database 2D measurements compatible with a heatmap."""
+
+        target_axes = tuple(
+            getattr(getattr(target_win, "param", None), "depends_on_", ())
+        )
+        if len(target_axes) != 2:
+            return []
+
+        run_list = getattr(self, "RunList", None)
+        all_run_metadata = getattr(run_list, "all_run_metadata", None)
+        if not callable(all_run_metadata):
+            return []
+
+        candidates = []
+        primary_key = TraceKey(target_win._dataset_key, target_win.param.name)
+        plotted = getattr(target_win, "heatmaps", {})
+        for run_id, metadata in all_run_metadata().items():
+            axes = tuple(metadata.get("sweep_parameters") or ())
+            if len(axes) != 2 or set(axes) != set(target_axes):
+                continue
+            guid = metadata.get("guid")
+            if not guid:
+                continue
+            source_key = self._current_dataset_key(guid)
+            for parameter_name in metadata.get("measure_parameters") or ():
+                heatmap_key = TraceKey(source_key, parameter_name)
+                if heatmap_key == primary_key or heatmap_key in plotted:
+                    continue
+                candidates.append(
+                    (f"ID:{run_id} {parameter_name}", heatmap_key)
+                )
+        return candidates
+
+
+    @_trusted_plot_action
+    def add_heatmap_to_plot(
+            self,
+            target_win,
+            source_identity,
+            parameter_name,
+            param=None,
+            ):
+        """Add a compatible 2D parameter as a layer on an existing heatmap."""
+
+        source_path = (
+            source_identity.database_path
+            if isinstance(source_identity, DatasetKey)
+            else None
+        )
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                source_path,
+                "adding a preview heatmap",
+                ):
+            return False
+
+        add_heatmap = getattr(target_win, "add_heatmap", None)
+        if (
+                target_win is None
+                or getattr(target_win, "operation_kind", None) != "plot2d"
+                or not callable(add_heatmap)
+                ):
+            self.show_status("Drop heatmaps onto a compatible heatmap plot.", 5000)
+            return False
+
+        if isinstance(source_identity, DatasetKey):
+            source_key = source_identity
+        else:
+            source_key = self._current_dataset_key(source_identity)
+        source_guid = source_key.guid
+
+        if param is None:
+            try:
+                param = self._parameter_from_key(source_key, parameter_name)
+            except Exception as err:
+                log_exception("Heatmap source run load failed", err, __name__)
+                self.show_error(
+                    "Run Load Failed",
+                    f"Could not load run with GUID {source_guid}.",
+                    str(err),
+                )
+                return False
+
+        if param is None or not getattr(param, "depends_on", ""):
+            self.show_status(f"No preview plot found for {parameter_name}.", 5000)
+            return False
+
+        source_axes = tuple(getattr(param, "depends_on_", ()))
+        target_axes = tuple(getattr(target_win.param, "depends_on_", ()))
+        if len(source_axes) != 2:
+            self.show_status("Only 2D measurements can be added as heatmaps.", 5000)
+            return False
+        if len(target_axes) != 2 or set(source_axes) != set(target_axes):
+            self.show_status(
+                f"Cannot add {parameter_name}; the heatmap axes do not match.",
+                5000,
+            )
+            return False
+
+        source_trace_key = TraceKey(source_key, param.name)
+        heatmaps = getattr(target_win, "heatmaps", {})
+        if source_trace_key in heatmaps:
+            self.show_status(
+                f"Skipped {parameter_name}; that heatmap is already shown.",
+                5000,
+            )
+            return False
+        if source_trace_key == getattr(target_win, "_trace_key", None):
+            self.show_status(
+                f"Skipped {target_win.label}; source and target are the same.",
+                5000,
+            )
+            return False
+
+        from_win = self._plot_window_for_param(
+            source_key,
+            param,
+            operation_kind="plot2d",
+            )
+        if from_win == target_win:
+            self.show_status(
+                f"Skipped {target_win.label}; source and target are the same.",
+                5000,
+            )
+            return False
+
+        if from_win is None:
+            from_win = self._open_hidden_trace_window(source_key, param, target_win)
+            if from_win is None:
+                return False
+
+        _axis_order, compatibility_error = _heatmap_layer_compatibility(
+            target_win,
+            from_win,
+        )
+        if compatibility_error is not None:
+            if compatibility_error == "the displayed value units do not match":
+                compatibility_error += (
+                    f" (source: {_window_display_unit(from_win) or 'unitless'};"
+                    f" target: {_window_display_unit(target_win) or 'unitless'})"
+                )
+            self.show_status(
+                f"Cannot add {parameter_name}; {compatibility_error}.",
+                5000,
+            )
+            if not getattr(from_win, "visible", False):
+                from_win.close()
+            return False
+
+        try:
+            added = bool(add_heatmap(from_win))
+        except Exception as err:
+            log_exception("Heatmap layer construction failed", err, __name__)
+            self.show_error(
+                "Heatmap Add Failed",
+                f"Could not add {parameter_name} to the heatmap.",
+                str(err),
+            )
+            added = False
+
+        if not getattr(from_win, "visible", False):
+            from_win.close()
+
+        if not added:
+            self.show_status(
+                f"Cannot add {parameter_name}; it is already shown or incompatible.",
+                5000,
+            )
+            return False
+
+        sync_layer_views = getattr(
+            target_win,
+            "_sync_secondary_heatmap_view_ranges",
+            None,
+        )
+        if callable(sync_layer_views):
+            sync_layer_views()
+
+        self.show_status(f"Added {from_win.label} to {target_win.label}.", 3000)
+        return True
+
+
+    def _parameter_from_guid(self, guid, parameter_name):
+        return self._parameter_from_key(self._current_dataset_key(guid), parameter_name)
+
+
+    def _parameter_from_key(self, dataset_key, parameter_name):
+        ds = self._dataset_for_key(dataset_key)
+        try:
+            return self._measurement_param_by_name(ds, parameter_name)
+        finally:
+            self._close_dataset_if_unowned(
+                ds,
+                context="Parameter lookup dataset cleanup failed",
+                )
+
+
+    def _measurement_param_by_name(self, dataset, parameter_name):
+        for param in dataset.get_parameters():
+            if param.name == parameter_name:
+                return param
+        return None
+
+
+    def _dataset_for_guid(self, guid):
+        return self._dataset_for_key(self._current_dataset_key(guid))
+
+
+    def _dataset_for_key(self, dataset_key):
+        handle = self._dataset_handle_for_key(dataset_key)
+        if handle is not None:
+            return handle.dataset
+        return self._load_dataset(dataset_key)
+
+
+    def _plot_window_for_param(self, dataset_key, param, operation_kind=None):
+        for win in self.windows:
+            try:
+                window_kind = getattr(
+                    win,
+                    "operation_kind",
+                    win.__class__.__name__,
+                    )
+                if (
+                        win._dataset_key == dataset_key
+                        and win.param.name == param.name
+                        and (
+                            operation_kind is None
+                            or window_kind == operation_kind
+                            )
+                        ):
+                    return win
+            except AttributeError:
+                continue
+        return None
+
+
+    def _open_hidden_trace_window(self, source_key, param, target_win):
+        before = set(id(win) for win in self.windows)
+        self.openPlot(guid=source_key, params=[param], show=False)
+
+        for win in reversed(self.windows):
+            if id(win) in before:
+                continue
+            try:
+                if win._dataset_key == source_key and win.param.name == param.name:
+                    if plot_refresh_required(win):
+                        target_win.toolbarRef.show()
+                    return win
+            except AttributeError:
+                continue
+
+        self.show_status(f"Could not prepare {param.name} for adding to the plot.", 5000)
+        return None
+
+
+    def _selected_measurement_params(self, dataset):
+        """
+        Returns the measurement parameters requested by the Measurement field.
+
+        """
+        params = [param for param in dataset.get_parameters() if param.depends_on != ""]
+        names = self._selected_measurement_names(
+            tuple(param.name for param in params),
+            dataset.run_id,
+        )
+        if names is None:
+            return None
+        selected_names = set(names)
+        return [param for param in params if param.name in selected_names]
+
+
+    def _selected_measurement_names(self, parameter_names, run_id):
+        """Apply the Measurement field to immutable parameter names."""
+        measurement_box = getattr(self, "measurementBox", None)
+        measurement = (
+            measurement_box.text().strip()
+            if measurement_box is not None
+            else "*"
+        )
+
+        if measurement in ("", "*"):
+            return tuple(parameter_names)
+
+        try:
+            index = int(measurement)
+        except ValueError:
+            self.show_status("Measurement must be a number or *.", 5000)
+            return None
+
+        if index < 1 or index > len(parameter_names):
+            self.show_status(
+                f"Run {run_id} has no measurement {index}.",
+                5000,
+            )
+            return None
+
+        return (parameter_names[index - 1],)
+
+
+    def _run_csv_export_request(self):
+        """Capture a run key and names without opening an export dataset."""
+        database_path = self.fileTextbox.text()
+        if not database_path:
+            self.show_status("Load a database before plotting or exporting.", 5000)
+            return None
+
+        run_id = self.selected_run_id
+        if run_id is None:
+            self.show_status("Enter a Run ID before plotting or exporting.", 5000)
+            return None
+
+        reload_if_changed = getattr(
+            self,
+            "_reload_if_database_instance_changed",
+            None,
+        )
+        if callable(reload_if_changed) and reload_if_changed(database_path):
+            self.show_status(
+                "Database was replaced; reloading before exporting the run.",
+                5000,
+            )
+            return None
+
+        selected_dataset = getattr(self, "ds", None)
+        selected_key = getattr(self, "_selected_dataset_key", None)
+        if (
+                selected_dataset is not None
+                and getattr(selected_dataset, "run_id", None) == run_id
+                and selected_key is not None
+                and selected_key.database_path
+                == logical_database_path(database_path)
+                ):
+            try:
+                parameter_names = tuple(
+                    param.name
+                    for param in _exportable_measurement_params(selected_dataset)
+                )
+            except Exception as error:
+                log_exception("Run parameter enumeration failed", error, __name__)
+                self.show_error(
+                    "Run Load Failed",
+                    "Could not read the selected run's measurements.",
+                    str(error),
+                )
+                return None
+            # Parameter enumeration may reuse an explicit-action dataset, but
+            # this new export request is rebound to the currently accepted full
+            # DatabaseInstance after the replacement guard above.
+            dataset_key = self._current_dataset_key(selected_key.guid)
+        else:
+            metadata = self._run_metadata_for_id(run_id)
+            guid = metadata.get("guid")
+            if not guid:
+                self.show_status(
+                    f"Run {run_id} is not available in the loaded database.",
+                    5000,
+                )
+                return None
+            dataset_key = self._current_dataset_key(str(guid))
+            parameter_names = tuple(
+                str(name)
+                for name in metadata.get("measure_parameters") or ()
+            )
+            if getattr(self, "_database_access_mode", None) == TRUSTED_LIVE_MODE:
+                # The trusted run list is populated progressively. Its initial
+                # measurement names may omit standalones until derived metadata
+                # arrives. An explicit export can enumerate a short-lived
+                # action view now, before the modal destination dialog.
+                dataset = None
+                try:
+                    dataset_key = self._bind_one_shot_dataset_key(dataset_key)
+                    dataset = self._load_run_csv_dataset(dataset_key)
+                    parameter_names = tuple(
+                        param.name
+                        for param in _exportable_measurement_params(dataset)
+                    )
+                    self._require_run_csv_source_current(dataset_key)
+                except DatabaseInstanceChangedError:
+                    self._handle_run_csv_source_replaced(dataset_key)
+                    return None
+                except Exception as error:
+                    log_exception("Run parameter enumeration failed", error, __name__)
+                    self.show_error(
+                        "Run Load Failed",
+                        "Could not read the selected run's measurements.",
+                        str(error),
+                    )
+                    return None
+                finally:
+                    if dataset is not None:
+                        try:
+                            close_dataset_connection(dataset)
+                        except Exception as error:
+                            log_exception(
+                                "CSV parameter dataset cleanup failed",
+                                error,
+                                __name__,
+                            )
+
+        requested_names = self._selected_measurement_names(
+            parameter_names,
+            run_id,
+        )
+        if requested_names is None:
+            return None
+        return dataset_key, requested_names, run_id
+
+
+    def _run_metadata_for_id(self, run_id):
+        """Return already-loaded run metadata without opening SQLite."""
+        run_list = getattr(self, "RunList", None)
+        all_run_metadata = getattr(run_list, "all_run_metadata", None)
+        if not callable(all_run_metadata):
+            return {}
+        runs = all_run_metadata()
+        metadata = runs.get(run_id)
+        if metadata is None:
+            metadata = runs.get(str(run_id))
+        return dict(metadata or {})
+
+
+    def _measurement_params_by_names(self, dataset, parameter_names):
+        """Resolve captured measurement names against a freshly loaded run."""
+        parameters = {
+            param.name: param for param in _exportable_measurement_params(dataset)
+        }
+        resolved = []
+        for name in parameter_names:
+            param = parameters.get(name)
+            if param is None:
+                raise ValueError(
+                    f"Measurement parameter {name!r} is not exportable in the "
+                    "freshly loaded run."
+                )
+            resolved.append(param)
+        return resolved
+
+
+    def _dataset_for_plot_target(self):
+        """
+        Loads the dataset requested by the Run field.
+
+        """
+        if not PlotActionsMixin._generation_gate_allows_action(
+                self,
+                operation="loading the selected run",
+                ):
+            return None
+        if not self.fileTextbox.text():
+            self.show_status("Load a database before plotting or exporting.", 5000)
+            return None
+
+        if getattr(self, "selected_run_id", None) is None:
+            self.show_status("Enter a Run ID before plotting or exporting.", 5000)
+            return None
+
+        reload_if_changed = getattr(
+            self,
+            "_reload_if_database_instance_changed",
+            None,
+        )
+        if callable(reload_if_changed) and reload_if_changed(self.fileTextbox.text()):
+            self.show_status(
+                "Database was replaced; reloading before opening the run.",
+                5000,
+            )
+            return None
+
+        run_id = self.selected_run_id
+        metadata = self._run_metadata_for_id(run_id)
+        guid = metadata.get("guid")
+        if not guid:
+            self.show_status(
+                f"Run ID {run_id} is not available in the loaded database.",
+                5000,
+            )
+            return None
+        dataset_key = self._current_dataset_key(str(guid))
+        self._plot_target_dataset_key = None
+        try:
+            dataset = self._load_dataset(dataset_key)
+            if getattr(dataset, "guid", None) != dataset_key.guid or int(
+                    getattr(dataset, "run_id", -1)
+                    ) != int(run_id):
+                self._close_dataset_if_unowned(dataset)
+                raise RuntimeError(
+                    "The selected GUID did not resolve to the requested run ID."
+                )
+            self._plot_target_dataset_key = dataset_key
+            return dataset
+        except DatabaseInstanceChangedError:
+            if callable(reload_if_changed):
+                reload_if_changed(self.fileTextbox.text())
+            self.show_status(
+                "Database was replaced; reloading before opening the run.",
+                5000,
+            )
+            return None
+        except Exception as error:
+            if not self._dataset_key_is_current(dataset_key):
+                if callable(reload_if_changed):
+                    reload_if_changed(self.fileTextbox.text())
+                self.show_status(
+                    "Database was replaced; reloading before opening the run.",
+                    5000,
+                )
+                return None
+            log_exception("Run ID load failed", error, __name__)
+            self.show_error(
+                "Run Load Failed",
+                f"Could not load Run ID {self.selected_run_id}.",
+                str(error),
+            )
+            return None
+
+
+    def _accepted_plot_target_key(self, dataset):
+        """Bind first sidecars and recheck before plot UI publication."""
+
+        dataset_key = getattr(self, "_plot_target_dataset_key", None)
+        if not isinstance(dataset_key, DatasetKey) or dataset_key.guid != str(
+                getattr(dataset, "guid", "")
+                ):
+            dataset_key = self._current_dataset_key(str(dataset.guid))
+        bound_key = PlotActionsMixin._bind_plot_dataset_key(self, dataset_key)
+        if bound_key is not None:
+            self._plot_target_dataset_key = bound_key
+            return bound_key
+        self.show_status(
+            "Database was replaced; reloading before opening the run.",
+            5000,
+        )
+        return None
+
+
+    def _measurement_dataframe(self, dataset, params):
+        """
+        Builds a flat CSV-friendly dataframe for the selected measurement data.
+
+        """
+        frames = []
+        prefix_columns = len(params) > 1
+        for param in params:
+            param_data = parameter_data_for_export(dataset, param.name)
+            columns = {}
+            for name, values in _csv_scalar_columns(param_data).items():
+                column_name = f"{param.name}.{name}" if prefix_columns else name
+                # Object samples may need both uint64 and negative int64, or
+                # exact integers alongside floats. Disable pandas' inference.
+                dtype: str | type[object] | None = object if values.dtype.hasobject else None
+                if values.dtype.kind in "iu":
+                    # Alignment adds blanks to shorter columns. Nullable
+                    # integers retain exact values instead of becoming floats.
+                    prefix = "U" if values.dtype.kind == "u" else ""
+                    dtype = f"{prefix}Int{values.dtype.itemsize * 8}"
+                columns[column_name] = pd.Series(values, dtype=dtype)
+            frames.append(pd.DataFrame(columns))
+
+        return pd.concat(frames, axis=1) if frames else pd.DataFrame()
+
+
+    def _default_export_filename(self, dataset, params):
+        """
+        Returns a default CSV export path.
+
+        """
+        database_folder = os.path.dirname(self.fileTextbox.text())
+        measurement = "all" if len(params) != 1 else params[0].name
+        filename = self._safe_filename(f"run_{dataset.run_id}_{measurement}.csv")
+        return os.path.join(database_folder or os.getcwd(), filename)
+
+
+    def _default_run_csv_export_filename(
+            self,
+            dataset_key,
+            parameter_names,
+            *,
+            run_id=None,
+            ):
+        """Return a CSV suggestion from a captured export request."""
+        if run_id is None:
+            run_list = getattr(self, "RunList", None)
+            run_id_for_guid = getattr(run_list, "run_id_for_guid", None)
+            if callable(run_id_for_guid):
+                run_id = run_id_for_guid(dataset_key.guid)
+        run_identifier = dataset_key.guid if run_id is None else run_id
+        measurement = (
+            "all" if len(parameter_names) != 1 else parameter_names[0]
+        )
+        filename = self._safe_filename(
+            f"run_{run_identifier}_{measurement}.csv"
+        )
+        database_folder = os.path.dirname(dataset_key.database_path)
+        return os.path.join(database_folder or os.getcwd(), filename)
+
+
+    def _default_preview_export_filename(self, dataset_key, parameter_name):
+        """Return a preview destination suggestion without opening its dataset."""
+        run_id = None
+        run_list = getattr(self, "RunList", None)
+        run_id_for_guid = getattr(run_list, "run_id_for_guid", None)
+        if callable(run_id_for_guid):
+            run_id = run_id_for_guid(dataset_key.guid)
+
+        selected_key = getattr(self, "_selected_dataset_key", None)
+        selected_dataset = getattr(self, "ds", None)
+        if run_id is None and selected_key == dataset_key and selected_dataset is not None:
+            run_id = getattr(selected_dataset, "run_id", None)
+
+        run_identifier = dataset_key.guid if run_id is None else run_id
+        filename = self._safe_filename(
+            f"run_{run_identifier}_{parameter_name}.csv",
+        )
+        database_folder = os.path.dirname(dataset_key.database_path)
+        return os.path.join(database_folder or os.getcwd(), filename)
+
+
+    def _safe_filename(self, filename):
+        """
+        Replaces path-hostile characters in a suggested filename.
+
+        """
+        return "".join(char if char.isalnum() or char in "._-" else "_" for char in filename)
+
+
+    @QtCore.pyqtSlot(object)
+    def add_ds_at(self, dataset_key: DatasetKey, ds=None):
+        """
+        Tracks a dataset used by one or more plot windows.
+
+        """
+        self._ensure_bound_plot_dataset_key_can_be_read(dataset_key)
+        handle = self._dataset_handle_for_key(dataset_key)
+        if handle is None:
+            ds = self._load_dataset(dataset_key) if ds is None else ds
+            assert ds.guid == dataset_key.guid
+
+            if not self._bound_plot_dataset_key_is_current(dataset_key):
+                self._close_dataset_if_unowned(
+                    ds,
+                    context="Replaced database dataset cleanup failed",
+                )
+                raise RuntimeError(
+                    "The database was replaced while its dataset was being acquired."
+                )
+            self.dataset_holder[dataset_key] = DatasetHandle(
+                dataset=ds,
+                database_identity=dataset_key.database_identity,
+                sidecar_identities=dataset_key.sidecar_identities,
+            )
+        else:
+            handle.retain()
+
+
+    @QtCore.pyqtSlot(object)
+    def remove_ds_at(self, dataset_key: DatasetKey):
+        """
+        Decreases the user count for a cached plot dataset.
+
+        """
+        handle = self.dataset_holder.get(dataset_key)
+        if handle is None:
+            self.show_status("Trying to remove dataset that does not exist.", 5000)
+            return
+
+        handle.release()
+
+        if handle.users <= 0:
+            del_time = self.config.get("runtime_settings.del_grace_period")
+
+            if del_time == 0:
+                self._evict_dataset_handle(dataset_key)
+
+            elif handle.delete_timer is None:
+                del_timer = QtCore.QTimer()
+                del_timer.setSingleShot(True)
+                handle.delete_timer = del_timer
+                del_timer.timeout.connect(
+                    lambda key=dataset_key: self._evict_dataset_handle(key)
+                )
+                del_timer.start(int(del_time * 1000))
+
+
+    def _current_dataset_key(self, guid: str) -> DatasetKey:
+        database_path = self.fileTextbox.text()
+        loaded_instance = getattr(self, "_loaded_database_instance", None)
+        if (
+                isinstance(loaded_instance, DatabaseInstance)
+                and loaded_instance.logical_path
+                == logical_database_path(database_path)
+                ):
+            return DatasetKey(
+                loaded_instance.logical_path,
+                guid,
+                loaded_instance.identity,
+                loaded_instance.resolved_path,
+                sidecar_identities=loaded_instance.sidecar_identities,
+            )
+        return DatasetKey(database_path, guid)
+
+
+    def _load_dataset(self, dataset_key: DatasetKey):
+        self._ensure_dataset_key_can_be_read(dataset_key)
+
+        prepared = getattr(self, "_trusted_plot_ready", {}).get(dataset_key)
+        if prepared is not None:
+            return prepared
+        if getattr(self, "_database_access_mode", None) == TRUSTED_LIVE_MODE:
+            handle = self._dataset_handle_for_key(dataset_key)
+            if handle is not None:
+                return handle.dataset
+            raise RuntimeError("Trusted plot metadata must be requested asynchronously.")
+
+        try:
+            load_kwargs = {}
+            if dataset_key.database_identity is not None:
+                load_kwargs["expected_database_identity"] = (
+                    dataset_key.database_identity
+                )
+            dataset = load_by_guid_read_only(
+                dataset_key.guid,
+                dataset_key.database_path,
+                **load_kwargs,
+            )
+        except Exception:
+            # A replacement can race the check above. The read layer rejects
+            # that identity change without consuming its sidecar; this second
+            # check starts MainWindow's replacement reload when applicable.
+            self._ensure_dataset_key_can_be_read(dataset_key)
+            raise
+        try:
+            self._ensure_dataset_key_can_be_read(dataset_key)
+        except Exception:
+            try:
+                close_dataset_connection(dataset)
+            finally:
+                raise
+        return dataset
+
+
+    def post_admin(self):
+        """
+        Updates the plot windows' internal track of other open windows.
+
+        """
+        for item in self.windows:
+            if isinstance(item, plot1d):
+                self.get_1d_wins(item)
+
+
+    def get_1d_wins(self, win):
+        """
+        Finds compatible 1D plot windows for adding secondary traces to win.
+
+        """
+        wins = []
+
+        for item in self.windows:
+            try:
+                compatible = _subplot_axis_order(
+                    win.axis_options,
+                    item.axis_options,
+                    source_is_cut=(
+                        getattr(item, "operation_kind", item.__class__.__name__)
+                        == "sweeper"
+                        ),
+                    shared_parameter=_subplot_shared_parameter(win),
+                    )
+                if compatible is not None and not _plot_has_trace_window(win, item):
+                    wins.append(item)
+            except (AttributeError, RuntimeError):
+                continue
+
+        win.update_line_picker(wins)