misleep 0.3.0__py3-none-any.whl

misleep/gui/main_window.py

@@ -0,0 +1,2699 @@
+# -*- coding: UTF-8 -*-
+"""Main window of the MiSleep GUI.
+
+All plotting is based on the annotation: the signal area shows the raw
+channels with sleep-state background colors, the spectrogram strip, the
+hypnogram, and a collection of dock widgets for channel/scoring tools.
+"""
+
+import copy
+import datetime
+import json
+import os
+import time
+from contextlib import contextmanager
+
+import numpy as np
+from matplotlib import pyplot as plt
+from matplotlib.backends.backend_qtagg import FigureCanvasQTAgg as FigureCanvas
+from matplotlib.collections import PolyCollection
+from PySide6.QtCore import QEvent, QTimer, Qt
+from PySide6.QtGui import QColor, QKeySequence, QShortcut
+from PySide6.QtWidgets import (
+    QAbstractItemView,
+    QAbstractSpinBox,
+    QApplication,
+    QComboBox,
+    QFileDialog,
+    QGridLayout,
+    QMainWindow,
+    QMessageBox,
+    QPushButton,
+    QScrollArea,
+    QSizePolicy,
+    QVBoxLayout,
+    QWidget,
+)
+
+from misleep.config import load_config, save_config, user_config_path
+from misleep.data import MiAnnotation, MiData
+from misleep.gui.config_dialog import SettingsDialog
+from misleep.gui.dialogs import (
+    AboutDialog,
+    AutoStageCausalTransformerDialog,
+    AutoStageLightGBMDialog,
+    EventListDialog,
+    HorizontalLineDialog,
+    LabelDialog,
+    SaveDataDialog,
+    SpindleDetectionDialog,
+    StateSpectralDialog,
+    SWADetectionDialog,
+    TransferResultDialog,
+    UserGuideDialog,
+)
+from misleep.gui.event_filters import WheelInputGuard
+from misleep.gui.qt_utils import (
+    ChannelListModel,
+    CollapsibleSection,
+    app_icon,
+    create_new_mianno,
+    identify_startend_color,
+)
+from misleep.gui.style import (
+    COLOR_TONES,
+    THEMES,
+    apply_theme,
+    resolved_theme,
+    retheme_figures,
+)
+from misleep.gui.uis.main_window_ui import Ui_MiSleep
+from misleep.gui.workers import SaveThread
+from misleep.io.annotation import available_annotation_readers, load_annotation
+from misleep.io import available_readers, available_writers, load_signal
+from misleep.logger import logger
+from misleep.utils.annotation import lst2group
+from misleep.viz.spectral import spectrogram_color_limits
+
+
+def _text_on(color_hex: str) -> str:
+    """Return black or white text for a background color (any theme)."""
+    c = QColor(color_hex)
+    lum = 0.299 * c.red() + 0.587 * c.green() + 0.114 * c.blue()
+    return "#000000" if lum > 150 else "#ffffff"
+
+
+class MainWindow(QMainWindow, Ui_MiSleep):
+    """Main window of MiSleep."""
+
+    def __init__(self, parent=None):
+        self._startup_started = time.perf_counter()
+        super().__init__(parent)
+        self.setupUi(self)
+
+        # Load configuration first so the GUI can honor the user's theme.
+        self.config = load_config()
+
+        # Apply the selected theme (light / dark): Qt style + fonts +
+        # matplotlib defaults, so the plot area matches the chrome.
+        self._theme_name = self.config.get("gui", "theme", fallback="light")
+        if self._theme_name not in THEMES:
+            self._theme_name = "light"
+        self._tone_name = self.config.get("gui", "color_tone", fallback="black")
+        if self._tone_name not in COLOR_TONES:
+            self._tone_name = "black"
+        app = QApplication.instance()
+        if app is not None:
+            apply_theme(app, self._theme_name, self._tone_name)
+        self._set_plot_colors()
+
+        logger.info(f"Initializing MiSleep {self.config['gui']['version']}")
+
+        self.midata = None
+        self.mianno = None
+
+        # Original data and label file paths
+        self.data_path = ""
+        self.anno_path = ""
+
+        # Initial params
+        self.current_sec = 0
+        self.show_duration = 30  # Seconds of duration to plot
+        self.total_seconds = 0  # Total seconds for plot
+        self.y_lims = None  # list of y lim for each channel
+        self.y_shift = None  # list of y shift for each channel
+        self.show_idx = None  # Channels to show in the plot area
+        self.state_map_dict = {int(key): value for key, value
+                               in json.loads(self.config["gui"]["statemap"]).items()}
+        self.state_color_dict = {int(key): value for key, value
+                                 in json.loads(self.config["gui"]["statecolor"]).items()}
+        # Migrate the legacy white INIT default without overriding any custom
+        # non-white color chosen by the user.
+        if self.state_map_dict.get(4, "").strip().upper() == "INIT" and \
+                str(self.state_color_dict.get(4, "")).lower() in \
+                {"white", "#fff", "#ffffff"}:
+            self.state_color_dict[4] = "#ececec"
+            self.config["gui"]["statecolor"] = json.dumps(
+                {str(k): v for k, v in self.state_color_dict.items()})
+        self.start_end_color_dict = dict(json.loads(self.config["gui"]["startendcolor"].replace("'", '"')).items())
+
+        self.ShowRangeCombo_dict = {0: 30, 1: 60, 2: 300, 3: 1800, 4: 3600}
+        self.FilterTypeCombo_dict = {
+            0: "bandpass",
+            1: "highpass",
+            2: "lowpass",
+            3: "bandstop",
+        }
+        self.current_spectrogram_idx = 0
+        self.spectrogram_percentile = 99.7
+        self.show_midata = None
+        self.epoch_length = 5
+        self.ac_time = None
+
+        # Signal area figure
+        self.signal_figure = plt.figure()
+        self.signal_ax = self.signal_figure.subplots()
+        self.signal_figure.tight_layout(h_pad=0, w_pad=0)
+        self.signal_figure.subplots_adjust(hspace=0)
+        self.signal_canvas = FigureCanvas(self.signal_figure)
+        self.signal_canvas.mpl_connect("button_release_event", self.click_signal)
+        # start and end axvline, only two lines
+        self.signal_start_end_axvline = []
+        self.signal_marker_axvline = []
+
+        # Start-end for labels
+        self.start_end = []
+        # Start-end for milliseconds, for start_end label
+        self.start_end_ms = []
+
+        # Hypnogram area figure
+        self.hypo_figure = plt.figure(layout="constrained")
+        self.hypo_ax = self.hypo_figure.subplots()
+        self.hypo_canvas = FigureCanvas(self.hypo_figure)
+        self.hypo_canvas.mpl_connect("button_release_event", self.click_hypo)
+        self.hypo_axvline = self.hypo_ax.axvline(
+            self.current_sec, color="gray", alpha=0.8)
+
+        # Caches for fast page flips (spectrogram / hypnogram are static
+        # between flips, so they are computed once and reused).
+        self._spec_full_cache = {}           # channel idx -> (f, t, Sxx) of whole file
+        self._spec_cache_max_sec = 4 * 3600  # longer files compute per window
+        self._hypo_key = None                # fingerprint of the drawn hypnogram base
+        self._hypo_revision = 0              # increments only when states change
+        self._hypo_steps = []                # base step artists of the hypnogram
+        self._hypo_transient = []            # per-flip overlay artists
+        self._signal_artists = {}            # signal-axes idx -> artists we own
+        self._spec_artist = None             # current spectrogram QuadMesh
+
+        # Initial params for widgets
+        self.channel_slm = ChannelListModel()
+
+        # Initial dialogs and secondary windows
+        self.about_dialog = AboutDialog(version=self.config["gui"]["version"],
+                                        update_time=self.config["gui"]["updatetime"])
+        # Secondary analysis windows are created on first use.  Constructing
+        # every Qt form during startup costs time even when most sessions only
+        # annotate signals.
+        self.spec_window = None
+        self.label_dialog = LabelDialog(config=self.config)
+        self.transfer_result_dialog = None
+        self.state_spectral_dialog = None
+        self.save_data_dialog = None
+        self.horizontal_line_dialog = None
+        # The horizontal_line dict contains the line value, line color, line comment
+        # example: {'ch1': [23.33, '#ff0000', '3 x Standard deviation', horizontalLineObject]}
+        self.horizontal_line = {}
+        self.axhline_horizontal = []
+
+        self.swa_detection_dialog = None
+        self.spindel_detection_dialog = None
+        self.auto_stage_lightGBM_dialog = None
+        self.auto_stage_causalTransformer_dialog = None
+
+        # Check whether operations are saved or not
+        self.is_saved = True
+
+        # Timer to auto-save annotations every 5 minutes
+        self.save_timer = QTimer()
+        self.save_timer.timeout.connect(self.auto_save)
+
+        # High-DPI / resolution: canvases track the scroll areas
+        self.SignalArea.installEventFilter(self)
+        self.HypnoArea.installEventFilter(self)
+        self.signal_canvas.installEventFilter(self)
+        self.hypo_canvas.installEventFilter(self)
+        # The mouse wheel over the signal / hypnogram panels flips pages
+        self.SignalArea.viewport().installEventFilter(self)
+        self.HypnoArea.viewport().installEventFilter(self)
+
+        # Unified right-hand sidebar (replaces the four separate docks)
+        self._build_sidebar()
+        self._rebuild_compact_tool_layouts()
+        self._constrain_inputs()
+        self.setMinimumSize(960, 600)
+        self.setWindowIcon(app_icon())
+
+        self.init_qt()
+
+    # ------------------------------------------------------------------
+    # Theme control
+    # ------------------------------------------------------------------
+    def _set_plot_colors(self):
+        """Cache the theme colors used by the matplotlib canvases."""
+        theme = resolved_theme(self._theme_name, self._tone_name)
+        self._plot_trace = theme["plot"]["trace"]
+        self._plot_grid = theme["plot"]["grid"]
+
+    def _update_theme_action(self):
+        """Keep the menu-bar theme action text in sync with the theme."""
+        if getattr(self, "theme_action", None) is not None:
+            self.theme_action.setText(
+                "Switch to Light Theme" if self._theme_name == "dark"
+                else "Switch to Dark Theme")
+
+    def _ensure_dialog(self, attribute, factory):
+        """Create a secondary window only when the user first opens it."""
+        dialog = getattr(self, attribute)
+        if dialog is None:
+            dialog = factory()
+            setattr(self, attribute, dialog)
+        return dialog
+
+    @contextmanager
+    def _busy_operation(self):
+        """Disable interaction during synchronous work and always restore it.
+
+        Export routines still contain libraries that must run on the GUI
+        thread (Qt dialogs and matplotlib).  This guard prevents accidental
+        input during that work and, importantly, restores the window after
+        success, cancellation, or an exception.
+        """
+        QApplication.setOverrideCursor(Qt.CursorShape.WaitCursor)
+        self.setEnabled(False)
+        QApplication.processEvents()
+        try:
+            yield
+        finally:
+            self.setEnabled(True)
+            QApplication.restoreOverrideCursor()
+            self.signal_canvas.update()
+            self.hypo_canvas.update()
+            self.update()
+            QApplication.processEvents()
+
+    def toggle_theme(self):
+        """Toggle between the light and dark themes and redraw everything."""
+        self._theme_name = "dark" if self._theme_name == "light" else "light"
+        app = QApplication.instance()
+        if app is not None:
+            apply_theme(app, self._theme_name, self._tone_name)
+        retheme_figures(self._theme_name, self._tone_name)
+        self._set_plot_colors()
+        self._update_theme_action()
+        # Persist the choice so the next launch keeps it
+        self.save_config({"theme": self._theme_name})
+
+        if self.midata is not None and self.mianno is not None:
+            self.redraw_all(second=self.current_sec)
+        else:
+            self.clear_refresh(clf=True)
+        logger.info("Theme switched to %s", THEMES[self._theme_name]["name"])
+
+    def _build_sidebar(self):
+        """Replace the four right docks with one tidy, fixed sidebar.
+
+        The dock contents are re-parented into collapsible sections
+        (Data / Channels / Scoring / Display) stacked in a single panel,
+        so the right side always looks clean regardless of window size.
+        """
+        self._sections = []
+        sidebar = QWidget()
+        sidebar.setObjectName("Sidebar")
+        sidebar.setAttribute(Qt.WidgetAttribute.WA_StyledBackground, True)
+        sidebar.setMinimumWidth(0)
+        sidebar.setSizePolicy(QSizePolicy.Policy.Ignored,
+                              QSizePolicy.Policy.Preferred)
+        vbox = QVBoxLayout(sidebar)
+        vbox.setContentsMargins(0, 0, 0, 0)
+        vbox.setSpacing(8)
+
+        def add_section(title, content, collapsed=False, stretch=0):
+            sec = CollapsibleSection(title, content, collapsed=collapsed)
+            vbox.addWidget(sec, stretch)
+            self._sections.append(sec)
+            return sec
+
+        # Section titles keep the original dock names (Meta / Channel /
+        # Annotation / Time), so the sidebar reads exactly like the old GUI.
+        add_section("Meta", self.MetaDock.widget(), collapsed=True)
+        add_section("Channel", self.ChannelDock.widget(), stretch=1)
+        add_section("Annotation", self.AnnotationDock.widget())
+        add_section("Time", self.TimeDock.widget())
+
+        # The sidebar lives in a scroll area (never clips on small screens)
+        # and keeps a fixed, comfortable width next to the plot area.
+        self.sidebar = sidebar
+        scroll = QScrollArea()
+        scroll.setObjectName("SidebarScroll")
+        scroll.setWidgetResizable(True)
+        scroll.setFrameShape(QScrollArea.Shape.NoFrame)
+        scroll.setWidget(sidebar)
+        scroll.setMinimumWidth(320)
+        scroll.setMaximumWidth(388)
+        scroll.setSizePolicy(QSizePolicy.Policy.Preferred,
+                             QSizePolicy.Policy.Expanding)
+        scroll.setMinimumHeight(120)
+        scroll.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff)
+        self.sidebar_scroll = scroll
+        self.gridLayout_3.addWidget(scroll, 0, 1, 3, 1)
+        self.gridLayout_3.setColumnStretch(0, 1)
+        self.gridLayout_3.setColumnStretch(1, 0)
+
+        # tidy, even spacing inside every dock-content grid
+        for grid in (self.gridLayout, self.gridLayout_2, self.gridLayout_4):
+            grid.setSpacing(6)
+            grid.setContentsMargins(8, 6, 8, 8)
+        self.formLayout.setSpacing(6)
+        self.formLayout.setContentsMargins(8, 6, 8, 8)
+        # the channel list takes the section's extra height
+        self.gridLayout.setRowStretch(4, 1)
+
+        # vertical alignment in the Annotation section: the state buttons
+        # share equal columns, and the save/marker/list row stretches evenly
+        self.gridLayout_2.setColumnStretch(2, 1)
+        self.gridLayout_2.setColumnStretch(3, 1)
+        self.gridLayout_2.setColumnMinimumWidth(2, 72)
+        self.gridLayout_2.setColumnMinimumWidth(3, 72)
+        for bt in (self.SaveLabelBt, self.MarkerListBt, self.StartEndListBt):
+            bt.setSizePolicy(QSizePolicy.Policy.Expanding,
+                             QSizePolicy.Policy.Fixed)
+
+        # The old docks are hidden - their widgets now live in the sidebar.
+        for dock in (self.MetaDock, self.ChannelDock,
+                     self.AnnotationDock, self.TimeDock):
+            self.removeDockWidget(dock)
+            dock.hide()
+
+    def _rebuild_compact_tool_layouts(self):
+        """Arrange the frequently used tools in predictable equal columns."""
+        # Annotation: three mutually-exclusive modes on one row, followed by
+        # one two-column state grid, two list buttons, and a full-width save.
+        anno = self.gridLayout_2
+        self.SleepStateRadio.setText("State")
+        self.LabelBt.hide()
+        self.line_4.hide()
+        for col, radio in enumerate(
+                (self.MarkerRadio, self.StartEndRadio, self.SleepStateRadio)):
+            anno.addWidget(radio, 0, col, 1, 1)
+            anno.setColumnStretch(col, 1)
+        anno.setColumnStretch(3, 0)
+        anno.setColumnMinimumWidth(3, 0)
+
+        anno.addWidget(self.ExtraStatePanel, 1, 0, 1, 3)
+        anno.addWidget(self.line_5, 2, 0, 1, 3)
+        save_row = self.SaveRowPanel.layout()
+        save_row.removeWidget(self.SaveLabelBt)
+        save_row.setStretch(0, 1)
+        save_row.setStretch(1, 1)
+        anno.addWidget(self.SaveRowPanel, 3, 0, 1, 3)
+        anno.addWidget(self.SaveLabelBt, 4, 0, 1, 3)
+
+        # Channel move controls get their own row below Percentile and line up
+        # with the three action buttons below the channel list.
+        channel = self.gridLayout
+        channel.addWidget(self.MoveChPanel, 2, 0, 1, 3)
+        move_row = self.MoveChPanel.layout()
+        move_row.setContentsMargins(0, 0, 0, 0)
+        move_row.setSpacing(6)
+        self.MoveLabel.setText("Move channel:")
+        for widget in (self.MoveLabel, self.MoveUpBt, self.MoveDownBt):
+            widget.setMinimumWidth(0)
+            # QWIDGETSIZE_MAX itself produces a warning in recent PySide6.
+            # This is still effectively unbounded inside the sidebar.
+            widget.setMaximumWidth(10000)
+            widget.setSizePolicy(QSizePolicy.Policy.Expanding,
+                                 QSizePolicy.Policy.Fixed)
+        move_row.setStretch(0, 1)
+        move_row.setStretch(1, 1)
+        move_row.setStretch(2, 1)
+
+    def _constrain_inputs(self):
+        """Align sidebar editors without forcing cramped fixed widths."""
+        for name in ("FilterLowSpin", "FilterHighSpin", "PercentileSpin",
+                     "SecondSpin", "SecondNumSpin", "multipleScalerEditor"):
+            spin = getattr(self, name, None)
+            if spin is not None:
+                spin.setMinimumWidth(76)
+                spin.setMaximumWidth(104)
+        for name in ("FilterTypeCombo",):
+            combo = getattr(self, name, None)
+            if combo is not None:
+                combo.setMinimumWidth(112)
+                combo.setMaximumWidth(156)
+        self.ShowRangeCombo.setMinimumWidth(0)
+        self.ShowRangeCombo.setMaximumWidth(16777215)
+        self.ShowRangeCombo.setSizePolicy(QSizePolicy.Policy.Expanding,
+                                          QSizePolicy.Policy.Fixed)
+        for edit in (self.DataPathEdit, self.AnnoPathEdit):
+            edit.setMinimumWidth(150)
+            edit.setToolTip(edit.text())
+            edit.textChanged.connect(edit.setToolTip)
+
+    # ------------------------------------------------------------------
+    # Initialization
+    # ------------------------------------------------------------------
+    def init_qt(self):
+        """Wire up all Qt widget signals."""
+        # MenuBar triggers
+        self.actionAbout.triggered.connect(self.about_dialog.exec)
+        self.actionConfig.triggered.connect(self.open_settings_dialog)
+        self.actionLoadData.triggered.connect(self.load_data)
+        self.actionLoadAnnotation.triggered.connect(self.load_anno)
+        self.actionStateSpectral.triggered.connect(self.state_spectral)
+        self.actionTransferResult.triggered.connect(self.transfer_result)
+        self.actionAddLine.triggered.connect(self.add_horizontal_line)
+        self.actionSWA_detection.triggered.connect(self.swa_detection)
+        self.actionSpindle_Detection.triggered.connect(self.spindle_detection)
+        self.actionLightGBM.triggered.connect(self.auto_stage_LightGBM)
+        self.actionCausalTransformer.triggered.connect(self.auto_stage_CausalTransformer)
+        self.actionSaveData.triggered.connect(self.save_data)
+
+        # Spectrogram percentile
+        self.PercentileSpin.setValue(self.spectrogram_percentile)
+        self.PercentileSpin.setRange(0, 100)
+        self.PercentileSpin.valueChanged.connect(self.spec_percentile_change)
+        # Default spectrogram channel
+        self.DefaultCh4SpecBt.clicked.connect(self.default_ch4Spec)
+
+        # Scroll bar
+        self.ScrollerBar.valueChanged.connect(self.scroller_change)
+        self.ScrollerBar.setSingleStep(self.epoch_length)
+        self.ScrollerBar.setPageStep(self.show_duration)
+
+        # Time edits
+        self.SecondSpin.valueChanged.connect(self.SecondSpin_change)
+        self.DateTimeEdit.dateTimeChanged.connect(self.DateTimeEdit_change)
+
+        # Channel operations
+        self.ShowChBt.clicked.connect(self.show_chs)
+        self.HideChBt.clicked.connect(self.hide_chs)
+        self.DeleteChBt.clicked.connect(self.delete_chs)
+        self.ScalerUpBt.clicked.connect(self.scaler_up)
+        self.ScalerDownBt.clicked.connect(self.scaler_down)
+        self.ShiftUpBt.clicked.connect(self.shift_up)
+        self.ShiftDownBt.clicked.connect(self.shift_down)
+        self.channel_slm.dataChanged.connect(self.channel_rename)
+        # Channel order is changed with the Up/Down buttons (declared in the
+        # .ui); editing only starts on double-click.
+        self.ChListView.setEditTriggers(
+            QAbstractItemView.DoubleClicked | QAbstractItemView.EditKeyPressed)
+        self.channel_slm.rowsMoved.connect(self._on_channel_list_changed)
+        self.channel_slm.rowsInserted.connect(self._on_channel_list_changed)
+        self.channel_slm.rowsRemoved.connect(self._on_channel_list_changed)
+        self._updating_ch_list = False
+        # Channel move arrows (declared in the .ui beside the percentile box)
+        self.MoveUpBt.clicked.connect(lambda: self.move_channel("up"))
+        self.MoveDownBt.clicked.connect(lambda: self.move_channel("down"))
+        # Make sure the move arrows always show their glyph (and an icon),
+        # even if a .ui rebuild ever drops the translated text.
+        if not self.MoveUpBt.text():
+            self.MoveUpBt.setText("\u25b2")
+        if not self.MoveDownBt.text():
+            self.MoveDownBt.setText("\u25bc")
+
+        # Filter
+        self.FilterTypeCombo.currentIndexChanged.connect(self.FilterTypeCombo_change)
+        self.FilterConfirmBt.clicked.connect(self.filter_confirm)
+
+        # Spectrum window
+        self.PlotSpecBt.clicked.connect(self.show_spec_window)
+
+        # Custom second spin edit and ShowRangeCombo
+        self.ShowRangeCombo.setEnabled(True)
+        self.SecondNumSpin.setDisabled(True)
+        self.SecondNumSpin.setRange(5, 3600)
+        self.SecondNumSpin.setValue(30)
+        self.SecondNumSpin.valueChanged.connect(self.SecondNumSpin_changed)
+        self.ShowRangeCombo.currentIndexChanged.connect(self.ShowRangeCombo_changed)
+        self.CustomSecondsCheck.clicked.connect(self.CustomSecondCheck_clicked)
+
+        # Label radio: start_end by default
+        self.SleepStateRadio.setChecked(True)
+        self.MarkerRadio.toggled.connect(lambda: self.radio_recheck(self.MarkerRadio))
+        self.SleepStateRadio.toggled.connect(lambda: self.radio_recheck(self.SleepStateRadio))
+        self.StartEndRadio.toggled.connect(lambda: self.radio_recheck(self.StartEndRadio))
+
+        # Label buttons
+        self.NREMBt.clicked.connect(self.nrem_label)
+        self.REMBt.clicked.connect(self.rem_label)
+        self.WakeBt.clicked.connect(self.wake_label)
+        self.InitBt.clicked.connect(self.init_label)
+
+        # Shortcuts
+        self.labelSc = QShortcut(QKeySequence("a"), self)
+        self.labelSc.activated.connect(self.append_start_end)
+        self.specSc = QShortcut(QKeySequence("s"), self)
+        self.specSc.activated.connect(self.show_spec_window)
+
+        self.next_pageSc = QShortcut(QKeySequence("Right"), self)
+        self.next_pageSc.activated.connect(self.next_page)
+        self.previous_pageSc = QShortcut(QKeySequence("Left"), self)
+        self.previous_pageSc.activated.connect(self.previous_page)
+        self.next_epochSc = QShortcut(QKeySequence("Down"), self)
+        self.next_epochSc.activated.connect(self.next_epoch)
+        self.previous_epochSc = QShortcut(QKeySequence("Up"), self)
+        self.previous_epochSc.activated.connect(self.previous_epoch)
+
+        # NOTE: page-flipping with the mouse wheel is handled only by the
+        # event filter on the signal / hypnogram areas (see eventFilter),
+        # so scrolling over docks/tools never moves the signal window.
+
+        # Load data and annotation shortcuts
+        self.load_dataSc = QShortcut(QKeySequence("Shift+D"), self)
+        self.load_dataSc.activated.connect(self.load_data)
+        self.load_annoSc = QShortcut(QKeySequence("Shift+A"), self)
+        self.load_annoSc.activated.connect(self.load_anno)
+
+        # Save labels
+        self.SaveLabelBt.clicked.connect(self.save_anno)
+        self.saveSc = QShortcut(QKeySequence("Ctrl+S"), self)
+        self.saveSc.activated.connect(self.save_anno)
+
+        # Dynamic state-label buttons in the Annotation dock
+        self._sync_state_buttons()
+
+        # Scalar input
+        self.MultipleScalerConfirmBt.clicked.connect(self.multiple_scaler)
+
+        self.change_Bts_status(True)
+        self._build_menus()
+        # Marker / start-end event list viewers (declared in the .ui beside Save)
+        self.MarkerListBt.clicked.connect(self.show_marker_list)
+        self.StartEndListBt.clicked.connect(self.show_start_end_list)
+        logger.info("MiSleep ready in %.3f s - open a data file to start",
+                    time.perf_counter() - self._startup_started)
+
+        # Wheel over spin boxes / combos must not change their values
+        app = QApplication.instance()
+        if app is not None:
+            self._wheel_input_guard = WheelInputGuard(app)
+            app.installEventFilter(self._wheel_input_guard)
+
+    def change_Bts_status(self, status=True):
+        """Enable/disable buttons according to whether data is loaded."""
+        meta_content = self.MetaDock.widget()
+        if meta_content is not None:
+            meta_content.setDisabled(status)
+        self.AcTimeEdit.setDisabled(status)
+        self.DeleteChBt.setDisabled(status)
+        self.HideChBt.setDisabled(status)
+        self.ScalerDownBt.setDisabled(status)
+        self.ShiftDownBt.setDisabled(status)
+        self.ShowChBt.setDisabled(status)
+        self.ScalerUpBt.setDisabled(status)
+        self.ShiftUpBt.setDisabled(status)
+        self.FilterConfirmBt.setDisabled(status)
+        self.DefaultCh4SpecBt.setDisabled(status)
+        self.FilterTypeCombo.setDisabled(status)
+        self.PlotSpecBt.setDisabled(status)
+        self.LabelBt.setDisabled(status)
+        self.StartEndRadio.setDisabled(status)
+        self.SleepStateRadio.setDisabled(status)
+        self.SaveLabelBt.setDisabled(status)
+        self.MarkerRadio.setDisabled(status)
+        self.MarkerListBt.setDisabled(status)
+        self.StartEndListBt.setDisabled(status)
+        self.MoveUpBt.setDisabled(status)
+        self.MoveDownBt.setDisabled(status)
+        for bt in getattr(self, "_state_btns", {}).values():
+            bt.setDisabled(status)
+        self.DateTimeEdit.setDisabled(status)
+        self.ShowRangeCombo.setDisabled(status)
+        self.SecondSpin.setDisabled(status)
+        self.labelSc.setEnabled(not status)
+        self.specSc.setEnabled(not status)
+        self.next_pageSc.setEnabled(not status)
+        self.previous_pageSc.setEnabled(not status)
+        self.next_epochSc.setEnabled(not status)
+        self.previous_epochSc.setEnabled(not status)
+        self.multipleScalerEditor.setDisabled(status)
+        self.MultipleScalerConfirmBt.setDisabled(status)
+
+        self.menuTools.setDisabled(status)
+        self.menuResult.setDisabled(status)
+        self._update_annotation_mode()
+        self._update_channel_action_states()
+
+    def _selected_channel_rows(self):
+        """Return unique selected channel rows in view order."""
+        return sorted({index.row() for index in self.ChListView.selectedIndexes()})
+
+    def _update_channel_action_states(self, *_args):
+        """Keep all channel actions synchronized with the list selection."""
+        loaded = self.midata is not None
+        selected = self._selected_channel_rows() if loaded else []
+        has_selection = bool(selected)
+        one_selected = len(selected) == 1
+        for widget in (
+                self.ShowChBt, self.HideChBt, self.DeleteChBt,
+                self.ScalerUpBt, self.ScalerDownBt, self.ShiftUpBt,
+                self.ShiftDownBt, self.multipleScalerEditor,
+                self.MultipleScalerConfirmBt, self.FilterTypeCombo,
+                self.FilterLowSpin, self.FilterHighSpin):
+            widget.setEnabled(loaded and has_selection)
+        self.FilterConfirmBt.setEnabled(loaded and one_selected)
+        self.DefaultCh4SpecBt.setEnabled(loaded and one_selected)
+        self.PlotSpecBt.setEnabled(loaded and one_selected)
+        self.MoveUpBt.setEnabled(loaded and one_selected and selected[0] > 0)
+        self.MoveDownBt.setEnabled(
+            loaded and one_selected and selected[0] < self.midata.n_channels - 1)
+        if loaded and has_selection:
+            self.FilterTypeCombo_change()
+
+    def _update_annotation_mode(self, *_args):
+        """Enable state choices only while the State mode is active."""
+        active = self.midata is not None and self.SleepStateRadio.isChecked()
+        for bt in getattr(self, "_state_btns", {}).values():
+            bt.setEnabled(active)
+
+    def _build_menus(self):
+        """Polish the menu bar: File extras, Settings, Help with user guide."""
+        # File: add "Save Annotation" and "Exit"
+        save_anno_action = self.menuFile.addAction(app_icon(), "Save Annotation", self.save_anno)
+        save_anno_action.setShortcut(QKeySequence("Ctrl+S"))
+        self.menuFile.insertAction(self.actionSaveData, save_anno_action)
+        self.menuFile.addSeparator()
+        self.menuFile.addAction("Exit", self.close)
+
+        # Help: Settings lives on its own top-level menu, not in About
+        self.menuHelp.removeAction(self.actionConfig)
+        # Help: About + User Guide (with a link to the online documentation)
+        self.menuHelp.addSeparator()
+        self.menuHelp.addAction(app_icon(), "User Guide…", self.show_user_guide)
+
+        # A dedicated Settings menu, placed between Result and Help
+        settings_menu = self.menuBar.addMenu("Settings")
+        settings_action = settings_menu.addAction(
+            app_icon(), "Settings…", self.open_settings_dialog)
+        settings_action.setToolTip("Open the in-application settings dialog")
+        settings_menu.addSeparator()
+        self.theme_action = settings_menu.addAction(
+            "Switch to Dark Theme", self.toggle_theme)
+        self.theme_action.setShortcut(QKeySequence("Ctrl+Shift+T"))
+        self._update_theme_action()
+        self.menuBar.insertMenu(self.menuHelp.menuAction(), settings_menu)
+
+    def show_user_guide(self):
+        """Open the in-app user guide (brief usage notes + online docs)."""
+        dialog = UserGuideDialog(self)
+        dialog.exec()
+
+    # ------------------------------------------------------------------
+    # Data / annotation loading
+    # ------------------------------------------------------------------
+    def load_data(self):
+        """Triggered by actionLoadData: ask for a signal file and open it."""
+        extensions = available_readers()
+        patterns = " ".join(f"*{ext}" for ext in extensions)
+        format_filters = ";;".join(
+            f"{ext[1:].upper()} files (*{ext})" for ext in extensions)
+        data_path, _ = QFileDialog.getOpenFileName(
+            self, "Select data file",
+            f"{self.config['gui']['openpath']}",
+            f"All supported signals ({patterns});;{format_filters};;All files (*)")
+
+        if data_path == "":
+            return
+        self.open_data(data_path)
+
+    def open_data(self, data_path):
+        """Load a signal file (no file dialog) and show it.
+
+        Used both by the GUI's file dialog and when MiSleep is launched
+        with a data file argument (``misleep data.mat``) or by
+        double-clicking a registered file.
+
+        Parameters
+        ----------
+        data_path : str
+            Path of any registered signal file to load.
+        """
+        load_started = time.perf_counter()
+        if not os.path.exists(data_path):
+            QMessageBox.about(
+                self, "Error",
+                f"Data file not found:\n{data_path}")
+            return
+
+        self.data_path = data_path
+        self.midata = None
+        try:
+            self.midata = load_signal(self.data_path)
+            if not isinstance(self.midata, MiData):
+                raise ValueError("The reader did not return valid MiData")
+        except Exception as exc:
+            logger.exception("Could not load signal file %s", self.data_path)
+            QMessageBox.critical(
+                self, "Could not load data",
+                f"MiSleep could not open this signal file.\n\n{exc}")
+            self.data_path = ""
+            self.change_Bts_status(True)
+            self.mianno = None
+            return
+        read_elapsed = time.perf_counter() - load_started
+
+        # Save config
+        self.save_config({"openpath": self.data_path})
+
+        # New file: drop the cached whole-file spectrograms
+        self._spec_full_cache = {}
+
+        # Set meta info
+        self.DataPathEdit.setText(self.data_path)
+        self.ac_time = datetime.datetime.strptime(self.midata.time, "%Y%m%d-%H:%M:%S")
+        self.AcTimeEdit.setDateTime(self.ac_time)
+
+        # Set channel infos
+        self.fill_channel_listView()
+
+        self.start_end = []
+        self.current_spectrogram_idx = 0
+        self.mianno = None
+        self.anno_path = ""
+        self.AnnoPathEdit.setText("")
+
+        self.clear_refresh(clf=True, draw=False)
+
+        try:
+            self.check_show()
+        except Exception as e:
+            logger.error(f"Check Show ERROR: {e}")
+        logger.info("Data timing: read %.3f s, initialize/draw %.3f s",
+                    read_elapsed, time.perf_counter() - load_started - read_elapsed)
+
+    def load_anno(self):
+        """Triggered by actionLoadAnnotation: ask for an annotation file."""
+        extensions = available_annotation_readers()
+        patterns = " ".join(f"*{ext}" for ext in extensions)
+        anno_path, _ = QFileDialog.getOpenFileName(
+            self, "Select annotation file",
+            f"{self.config['gui']['openpath']}",
+            f"All supported annotations ({patterns});;All files (*)")
+
+        if anno_path == "":
+            return
+        self.open_annotation(anno_path)
+
+    def open_annotation(self, anno_path):
+        """Load an annotation file (no file dialog).
+
+        Used both by the GUI's file dialog and when MiSleep is launched
+        with an annotation argument (``misleep data.mat anno.txt``).
+
+        Parameters
+        ----------
+        anno_path : str
+            Path of the annotation ``.txt`` file.
+        """
+        load_started = time.perf_counter()
+        if not os.path.exists(anno_path):
+            QMessageBox.about(self, "Error", f"Annotation file not found:\n{anno_path}")
+            return
+
+        self.anno_path = anno_path
+        _mianno = self.mianno
+
+        try:
+            self.mianno = load_annotation(self.anno_path, state_map=self.state_map_dict)
+        except AssertionError as e:
+            if e.args and e.args[0] == "Empty":
+                if isinstance(self.midata, MiData):
+                    self.mianno = create_new_mianno(self.midata.duration)
+                else:
+                    QMessageBox.about(
+                        self, "Error",
+                        "To create a new annotation file, load a data file first.")
+                    self.anno_path = ""
+                    self.change_Bts_status(True)
+                    self.mianno = None
+                    return
+            else:
+                QMessageBox.critical(self, "Could not load annotation",
+                                     "The annotation file is invalid.")
+                self.anno_path = ""
+                self.mianno = _mianno
+                return
+        except Exception as exc:
+            logger.exception("Could not load annotation file %s", self.anno_path)
+            QMessageBox.critical(self, "Could not load annotation",
+                                 f"MiSleep could not open this annotation.\n\n{exc}")
+            self.anno_path = ""
+            self.mianno = _mianno
+            return
+
+        # Save config
+        self.save_config({"openpath": self.anno_path})
+
+        # Set meta info
+        self.AnnoPathEdit.setText(self.anno_path)
+
+        self.clear_refresh(clf=True, draw=False)
+
+        try:
+            self.check_show(_mianno)
+        except Exception as e:
+            logger.error(f"Check Show ERROR: {e}")
+        logger.info("Annotation load and redraw completed in %.3f s",
+                    time.perf_counter() - load_started)
+
+    def check_show(self, mianno=None):
+        """Validate data/annotation and draw everything.
+
+        Parameters
+        ----------
+        mianno : MiAnnotation, optional
+            Keep the previous annotation when loading a new one failed.
+        """
+        if not isinstance(self.midata, MiData):
+            QMessageBox.about(self, "Error", "Load data file first.")
+            self.midata = None
+            self.mianno = None
+            return
+
+        # heal the canvases before (re)attaching them to the scroll areas
+        self._repair_canvases()
+
+        if isinstance(self.midata, MiData) and not isinstance(self.mianno, MiAnnotation):
+            self.mianno = create_new_mianno(self.midata.duration)
+        self._hypo_revision += 1
+
+        self.show_idx = list(range(self.midata.n_channels))
+        self.y_lims = [float(np.max(np.abs(each[:1000])))
+                       for each in self.midata.signals]
+        self.y_lims = [1e-3 if each == 0.0 else each for each in self.y_lims]
+        self.y_shift = [0 for _ in range(self.midata.n_channels)]
+
+        if abs(self.midata.duration - self.mianno.anno_length) >= 600:
+            QMessageBox.about(self, "Error", "Data and annotation do not match!")
+            self.anno_path = ""
+            self.AnnoPathEdit.setText(self.anno_path)
+            if mianno:
+                self.mianno = mianno
+            if not isinstance(self.mianno, MiAnnotation):
+                self.mianno = create_new_mianno(self.midata.duration)
+        self.total_seconds = self.midata.duration if \
+            self.midata.duration < self.mianno.anno_length else self.mianno.anno_length
+        self.reset_sec_limit()
+
+        self.hypo_ax = self.hypo_figure.subplots(nrows=1, ncols=1)
+        # new axes: the cached hypnogram base must be rebuilt
+        self._hypo_key = None
+        self._hypo_steps = []
+        self._hypo_transient = []
+
+        # Set canvases for the plot areas
+        # Keep the canvases hidden until their final axes and DPI-aware size
+        # are ready.  Otherwise Qt briefly paints the tiny default figure and
+        # users see it grow after loading or adding a filtered channel.
+        self.signal_canvas.hide()
+        self.hypo_canvas.hide()
+        self.SignalArea.setWidget(self.signal_canvas)
+        self.HypnoArea.setWidget(self.hypo_canvas)
+
+        self.horizontal_line = {}
+        for channel in self.midata.channels:
+            self.horizontal_line[channel] = []
+
+        self.redraw_all(second=0)
+        self.change_Bts_status(False)
+
+        self.setWindowTitle(
+            f"MiSleep - {os.path.basename(self.data_path)} - {os.path.basename(self.anno_path)}")
+        self.start_end = []
+        self.mianno._state_map = self.state_map_dict
+
+        logger.info(f"Load SUCCEED: data - {self.data_path}, anno - {self.anno_path}")
+
+        # Load feedback
+        logger.info(
+            "Loaded: %s - %d channel(s), %d s",
+            os.path.basename(self.data_path),
+            self.midata.n_channels, self.total_seconds)
+
+        # Start the auto-save timer (5 min)
+        self.save_timer.start(60 * 5 * 1000)
+
+        # Fit the canvases to the (high-DPI aware) window size
+        self._fit_canvases()
+        self.signal_canvas.show()
+        self.hypo_canvas.show()
+
+    def reset_sec_limit(self):
+        """Update scrollbar / spin / datetime limits when show duration changes."""
+        self.ScrollerBar.setRange(0, self.total_seconds - self.show_duration)
+        self.SecondSpin.setRange(0, self.total_seconds - self.show_duration)
+
+        self.DateTimeEdit.blockSignals(True)
+        self.DateTimeEdit.setDateTimeRange(
+            self.ac_time,
+            self.ac_time + datetime.timedelta(seconds=self.total_seconds - self.show_duration))
+        self.DateTimeEdit.blockSignals(False)
+
+    # ------------------------------------------------------------------
+    # Plotting
+    # ------------------------------------------------------------------
+    def clear_refresh(self, clf=False, draw=True):
+        """Clear and refresh all plot canvases."""
+        if clf:
+            self.signal_figure.clf()
+            self.hypo_figure.clf()
+            # the old axes are gone; force a rebuild on the next plot
+            self.signal_ax = None
+            self._signal_artists = {}
+            self._spec_artist = None
+            self._hypo_key = None
+            self._hypo_steps = []
+            self._hypo_transient = []
+
+        if not draw:
+            return
+
+        self.hypo_figure.canvas.draw()
+        self.hypo_figure.canvas.flush_events()
+        self.signal_figure.canvas.draw()
+        self.signal_figure.canvas.flush_events()
+
+    def _repair_canvases(self):
+        """Recreate a main canvas whose matplotlib figure was closed.
+
+        A stray pyplot ``close()`` in some export routine used to kill the
+        main figures, freezing the signal/hypnogram panels.  With the
+        source fixed this should never happen, but the guard keeps the
+        window self-healing anyway.
+        """
+        import matplotlib.pyplot as plt
+
+        def alive(fig):
+            try:
+                return (plt.fignum_exists(fig.number)
+                        and plt.figure(fig.number) is fig)
+            except Exception:  # pragma: no cover
+                return False
+
+        if not alive(self.signal_figure):
+            self.signal_figure = plt.figure()
+            self.signal_ax = None
+            self.signal_canvas = FigureCanvas(self.signal_figure)
+            self.signal_canvas.mpl_connect("button_release_event", self.click_signal)
+            self.signal_canvas.installEventFilter(self)
+            self.SignalArea.setWidget(self.signal_canvas)
+            self._signal_artists = {}
+            self._spec_artist = None
+            logger.warning("Signal canvas was closed externally - recreated")
+
+        if not alive(self.hypo_figure):
+            self.hypo_figure = plt.figure(layout="constrained")
+            self.hypo_ax = self.hypo_figure.subplots()
+            self.hypo_canvas = FigureCanvas(self.hypo_figure)
+            self.hypo_canvas.mpl_connect("button_release_event", self.click_hypo)
+            self.hypo_canvas.installEventFilter(self)
+            self.HypnoArea.setWidget(self.hypo_canvas)
+            self._hypo_key = None
+            self._hypo_steps = []
+            self._hypo_transient = []
+            logger.warning("Hypnogram canvas was closed externally - recreated")
+
+    def _fit_canvases(self):
+        """Resize the matplotlib figures to match their widgets.
+
+        The widget size is converted to **device pixels** (multiplied by
+        ``devicePixelRatio``) before being fed to ``set_size_inches``, so
+        the figure fills the widget exactly on high-DPI / scaled displays
+        (e.g. 2K at 125-150 %). A modest minimum keeps scrollbars instead
+        of a crushed plot.
+        """
+        try:
+            sig_dpr = self.signal_canvas.devicePixelRatioF() or 1.0
+            sig_w = self.signal_canvas.width() * sig_dpr
+            sig_h = self.signal_canvas.height() * sig_dpr
+            if sig_w < 50 or sig_h < 50:
+                sig_w = self.SignalArea.viewport().width() * sig_dpr
+                sig_h = self.SignalArea.viewport().height() * sig_dpr
+            if sig_w > 50 and sig_h > 50:
+                self.signal_figure.set_size_inches(
+                    sig_w / self.signal_figure.dpi,
+                    sig_h / self.signal_figure.dpi)
+                self.signal_canvas.setMinimumSize(300, 200)
+                self._apply_signal_layout()
+                self.signal_figure.canvas.draw_idle()
+
+            hypo_dpr = self.hypo_canvas.devicePixelRatioF() or 1.0
+            hypo_w = self.hypo_canvas.width() * hypo_dpr
+            hypo_h = self.hypo_canvas.height() * hypo_dpr
+            if hypo_w < 50 or hypo_h < 50:
+                hypo_w = self.HypnoArea.viewport().width() * hypo_dpr
+                hypo_h = self.HypnoArea.viewport().height() * hypo_dpr
+            if hypo_w > 50 and hypo_h > 50:
+                self.hypo_figure.set_size_inches(
+                    hypo_w / self.hypo_figure.dpi,
+                    max(1.0, hypo_h / self.hypo_figure.dpi))
+                self.hypo_canvas.setMinimumSize(300, 60)
+                self.hypo_figure.canvas.draw_idle()
+        except Exception as e:  # pragma: no cover
+            logger.debug(f"fit canvases skipped: {e}")
+
+    def eventFilter(self, obj, event):
+        """Track canvas/scroll-area resizes; flip pages on mouse wheel."""
+        if event.type() == QEvent.Type.Resize:
+            if obj in (self.signal_canvas, self.hypo_canvas,
+                       self.SignalArea, self.HypnoArea):
+                self._fit_canvases()
+        elif event.type() == QEvent.Type.Wheel:
+            if obj in (self.SignalArea.viewport(), self.HypnoArea.viewport(),
+                       self.signal_canvas, self.hypo_canvas):
+                delta = event.angleDelta().y()
+                if delta < 0:
+                    self.next_page()
+                elif delta > 0:
+                    self.previous_page()
+                return True
+        return super().eventFilter(obj, event)
+
+    def resizeEvent(self, event):
+        """Keep the matplotlib canvases in sync with the window size."""
+        super().resizeEvent(event)
+        self._fit_canvases()
+
+    def showEvent(self, event):
+        """Fit the canvases once the window is actually shown."""
+        super().showEvent(event)
+        QTimer.singleShot(0, self._fit_canvases)
+
+    def _choose_tick_step(self, duration):
+        """Pick a tick interval (seconds) so ~6-24 x ticks are shown."""
+        for s in (5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600):
+            if duration / s <= 24:
+                return s
+        return 3600
+
+    def plot_signals(self, flush=True, clf=True, replot_axes=None):
+        """Plot the signal area: spectrogram strip + one box per channel.
+
+        Every channel gets its own axes (box) with its own y scale, so
+        the boxes are independent. The figure fills the whole signal
+        widget (see :meth:`_fit_canvases`).
+
+        Parameters
+        ----------
+        flush : bool
+            Whether to redraw the canvas.
+        clf, replot_axes : kept for API compatibility (always full redraw).
+        """
+        n = len(self.show_idx)
+        need = n + 1  # spectrogram strip + one box per channel
+        # Reuse the existing axes when the channel count is unchanged - much
+        # faster than recreating them on every page flip.
+        current = getattr(self, "signal_ax", None)
+        structure_changed = current is None or not isinstance(current, (list, tuple)) \
+                or len(current) != need
+        if structure_changed:
+            # No event-loop turn occurs between hide/show, so the user sees
+            # only the completed layout, never matplotlib's resize stages.
+            self.signal_canvas.hide()
+            self.signal_figure.clf()
+            self.signal_ax = list(self.signal_figure.subplots(
+                nrows=need, ncols=1,
+                gridspec_kw={"height_ratios": [0.8] + [1.0] * n}))
+            self._signal_artists = {}
+            self._spec_artist = None
+        else:
+            # Remove only the artists we own from the previous flip - far
+            # cheaper than clearing the whole axes.
+            for ax_idx, artists in self._signal_artists.items():
+                for art in artists:
+                    try:
+                        art.remove()
+                    except Exception:
+                        pass
+            self._signal_artists = {}
+        self.plot_spectrogram()
+        # visible frames around every panel (spectrogram strip + boxes)
+        self._style_signal_boxes()
+
+        # Sleep-state groups inside the current window
+        sleep_state = self.mianno.sleep_state[
+            self.current_sec: self.current_sec + self.show_duration + 1]
+        sleep_state = lst2group([i, each] for i, each in enumerate(sleep_state))
+
+        tick_step = self._choose_tick_step(self.show_duration)
+
+        for i, each in enumerate(self.show_idx):
+            ax = self.signal_ax[i + 1]
+            y_lim = self.y_lims[each]
+            y_shift = self.y_shift[each]
+            sf = self.midata.sf[each]
+
+            seg = self.midata.signals[each][
+                int(self.current_sec * sf): int(
+                    (self.current_sec + self.show_duration) * sf)]
+            # Short windows (up to ~3 min at 300 Hz) keep every sample;
+            # long windows use a min/max envelope so the waveform keeps its
+            # shape without the obvious thinning of every-Nth decimation.
+            if len(seg) <= 60000:
+                xs, ys = None, seg
+            else:
+                xs, ys = self._decimate_trace(seg)
+            if xs is None:
+                line, = ax.plot(ys, color=self._plot_trace, linewidth=0.5)
+            else:
+                line, = ax.plot(xs, ys, color=self._plot_trace, linewidth=0.5)
+            self._signal_artists.setdefault(i + 1, []).append(line)
+            ax.set_ylim(ymin=-y_lim + y_shift, ymax=y_lim + y_shift)
+            ax.set_xlim(xmin=0, xmax=self.show_duration * sf)
+            ax.xaxis.set_ticks([])
+            ax.yaxis.set_ticks([])
+            ax.set_ylabel(f"{self.midata.channels[each]}\n{y_lim:.2e}")
+
+            # grid lines: 5 s for short windows, tick step for long ones
+            grid_step = 5 if self.show_duration < 300 else tick_step
+            for pos_ in range(0, self.show_duration, grid_step):
+                grid_line = ax.axvline(pos_ * sf, color=self._plot_grid,
+                                       linestyle="--", linewidth=1, alpha=0.45)
+                self._signal_artists[i + 1].append(grid_line)
+
+            # Sleep-state background: one rectangle per run (the fill spans
+            # the full height, so two x-points are exact and cheap to draw)
+            for state in sleep_state:
+                fill = ax.fill_between(
+                    [int(state[0] * sf), int(state[1] * sf)],
+                    -y_lim + y_shift, y_lim + y_shift,
+                    facecolor=self.state_color_dict[state[2]],
+                    alpha=float(self.config["gui"]["statecolorbgalpha"]))
+                self._signal_artists[i + 1].append(fill)
+
+        # Time ticks only on the last channel box (auto-reduced for long windows)
+        last_sf = self.midata.sf[self.show_idx[-1]]
+        self.signal_ax[-1].xaxis.set_ticks(
+            [int(each * last_sf) for each in range(0, self.show_duration + 1, tick_step)],
+            range(self.current_sec, self.current_sec + self.show_duration + 1, tick_step),
+            rotation=45)
+        if self.show_duration < 300:
+            self.signal_ax[-1].xaxis.set_ticks(
+                [int(each * last_sf) for each in range(0, self.show_duration + 1)],
+                minor=True)
+
+        if self.StartEndRadio.isChecked():
+            self.plot_start_end_line(flush=False, ms=True)
+        if self.SleepStateRadio.isChecked():
+            self.plot_start_end_line(flush=False)
+        self.plot_marker_line(flush=False)
+        self.plot_start_end_label_line(flush=False)
+        self.plot_horizontal_line(flush=False)
+
+        # Keep the panels tightly packed (no gaps between boxes); the full
+        # tight_layout runs on resize only (see _fit_canvases), not on every
+        # page flip - that alone shaves ~20 ms off each flip.
+        self.signal_figure.subplots_adjust(hspace=0)
+
+        if flush:
+            self.signal_figure.canvas.draw()
+            self.signal_figure.canvas.flush_events()
+        if structure_changed:
+            self._fit_canvases()
+            self.signal_canvas.show()
+
+    def _apply_signal_layout(self):
+        """Tighten the signal figure layout so the panels touch each other."""
+        try:
+            self.signal_figure.tight_layout(h_pad=0, w_pad=0)
+            self.signal_figure.subplots_adjust(hspace=0)
+        except Exception as e:  # pragma: no cover
+            logger.debug(f"signal layout skipped: {e}")
+
+    def _style_signal_boxes(self):
+        """Give every signal panel a visible frame so the channels don't
+        look like they float together (all four spines on, theme edge)."""
+        edge = resolved_theme(
+            self._theme_name, self._tone_name)["mpl"]["axes.edgecolor"]
+        for ax in self.signal_ax:
+            for spine in ax.spines.values():
+                spine.set_visible(True)
+                spine.set_edgecolor(edge)
+                spine.set_linewidth(0.9)
+
+    @staticmethod
+    def _decimate_trace(sig, bins=12000):
+        """Min/max envelope decimation that preserves the signal shape.
+
+        Naive every-Nth sampling makes dense EEG look visibly thinned and
+        can alias rhythmic features; plotting the min/max of each bin keeps
+        the waveform envelope intact while bounding the draw cost.
+        """
+        n = len(sig)
+        if n <= bins * 2:
+            return np.arange(n), sig
+        step = int(np.ceil(n / bins))
+        n_bins = n // step
+        trimmed = sig[: n_bins * step].reshape(n_bins, step)
+        mn = trimmed.min(axis=1)
+        mx = trimmed.max(axis=1)
+        xs = np.repeat(np.arange(n_bins) * step, 2)
+        ys = np.empty(2 * n_bins)
+        ys[0::2] = mn
+        ys[1::2] = mx
+        return xs, ys
+
+    def replot_sleep_state_bg(self, state):
+        """Replot the sleep-state background of the selected start-end area."""
+        replot_start = 0 if self.current_sec >= self.start_end[0] \
+            else (self.start_end[0] - self.current_sec)
+        replot_end = self.show_duration if (
+            self.current_sec + self.show_duration <= self.start_end[1]
+        ) else (self.start_end[1] - self.current_sec)
+
+        for i, each in enumerate(self.show_idx):
+            y_lim = self.y_lims[each]
+            y_shift = self.y_shift[each]
+            sf = self.midata.sf[each]
+            x = range(int(replot_start * sf), int(replot_end * sf))
+            cover = self.signal_ax[i + 1].fill_between(
+                x, -y_lim + y_shift, y_lim + y_shift,
+                facecolor=resolved_theme(
+                    self._theme_name, self._tone_name)["plot"]["bg"], alpha=1)
+            fill = self.signal_ax[i + 1].fill_between(
+                x, -y_lim + y_shift, y_lim + y_shift,
+                facecolor=self.state_color_dict[state],
+                alpha=float(self.config["gui"]["statecolorbgalpha"]))
+            self._signal_artists.setdefault(i + 1, []).extend([cover, fill])
+        self.signal_figure.canvas.draw()
+        self.signal_figure.canvas.flush_events()
+
+    def spec_percentile_change(self):
+        """Triggered by the spectrogram percentile spin box."""
+        self.spectrogram_percentile = self.PercentileSpin.value()
+        self.plot_spectrogram(flush=True)
+
+    def default_ch4Spec(self):
+        """Set the selected channel as the default spectrogram channel."""
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        if len(selected_channel) != 1:
+            QMessageBox.about(
+                self, "Error",
+                "Select one channel to be the default channel for spectrogram.")
+            return
+        self.current_spectrogram_idx = selected_channel[0]
+        self.plot_spectrogram(flush=True)
+
+    def plot_spectrogram(self, flush=False):
+        """Redraw the spectrogram strip (cached whole-file STFT when possible)."""
+        if self.midata is None:
+            return
+        from misleep.preprocessing.spectral import spectrogram
+        # remove the previous spectrogram artist (cheaper than clearing axes)
+        if getattr(self, "_spec_artist", None) is not None:
+            try:
+                self._spec_artist.remove()
+            except Exception:
+                pass
+            self._spec_artist = None
+        freq_range = [float(x) for x in self.config["gui"]["freq_range"].strip("[]").split(",")]
+        ch = self.current_spectrogram_idx
+        sf = self.midata.sf[ch]
+
+        # Cache the STFT of the whole file per channel; page flips then only
+        # slice the cached spectrogram instead of recomputing it.
+        if ch not in self._spec_full_cache:
+            if self.midata.duration <= self._spec_cache_max_sec:
+                f, t, Sxx = spectrogram(
+                    signal=self.midata.signals[ch], sf=sf,
+                    band=freq_range, step=1, win_sec=5, norm=True)
+                self._spec_full_cache[ch] = (f, t, Sxx)
+            else:
+                self._spec_full_cache[ch] = None  # too long: per-window
+
+        cached = self._spec_full_cache.get(ch)
+        if cached is not None:
+            f, t, Sxx = cached
+            sel = (t >= self.current_sec) & (t <= self.current_sec + self.show_duration)
+            t = t[sel]
+            Sxx = Sxx[:, sel]
+        else:
+            f, t, Sxx = spectrogram(
+                signal=self.midata.signals[ch][
+                    int(self.current_sec * sf): int(
+                        (self.current_sec + self.show_duration) * sf)],
+                sf=sf, band=freq_range, step=1, win_sec=5, norm=True)
+
+        # Long windows: cap the number of time columns drawn
+        if t.size > 2000:
+            step_t = max(1, -(-t.size // 2000))
+            t = t[::step_t]
+            Sxx = Sxx[:, ::step_t]
+
+        cmap_name = self.config.get("gui", "spectrogram_cmap", fallback="jet")
+        try:
+            cmap = plt.get_cmap(cmap_name)
+        except ValueError:
+            cmap = plt.get_cmap("jet")
+        vmin, vmax = spectrogram_color_limits(Sxx, self.spectrogram_percentile)
+
+        self.signal_ax[0].set_xticks([])
+        # Pin the horizontal extent explicitly: with reused axes the
+        # auto-limit can stay stuck at a previous (longer) window, which
+        # compresses the strip to a fraction of its width.
+        self.signal_ax[0].set_xlim(t.min(), t.max())
+        self.signal_ax[0].set_ylim(freq_range)
+        self.signal_ax[0].set_ylabel(f"{self.midata.channels[ch]}")
+        # Match v2's dark low-power background even in the light theme and
+        # eliminate axes-color seams around the pcolormesh.
+        self.signal_ax[0].set_facecolor(cmap(0.0))
+        self._spec_artist = self.signal_ax[0].pcolormesh(
+            t, f, Sxx, cmap=cmap, vmin=vmin, vmax=vmax, shading="auto")
+
+        if flush:
+            self.signal_figure.canvas.draw()
+            self.signal_figure.canvas.flush_events()
+
+    def plot_start_end_line(self, flush=True, ms=False):
+        """Plot the interactive start/end selection lines in the signal area."""
+        start_end = self.start_end_ms if ms else self.start_end
+        for axvline in self.signal_start_end_axvline:
+            try:
+                axvline.remove()
+            except Exception:
+                pass
+        self.signal_start_end_axvline = []
+        for i, each in enumerate(start_end):
+            if self.current_sec <= each <= self.current_sec + self.show_duration:
+                for idx, show_ in enumerate(self.show_idx):
+                    y_lim = self.y_lims[show_]
+                    y_shift = self.y_shift[show_]
+                    sf = self.midata.sf[show_]
+                    if ms:
+                        x = round((each - self.current_sec) * sf, 3)
+                    else:
+                        x = int((each - self.current_sec) * sf)
+
+                    if i in (0, 1):
+                        self.signal_start_end_axvline.append(
+                            self.signal_ax[idx + 1].axvline(x, color="lime", alpha=1))
+
+                if i == 0:
+                    self.signal_start_end_axvline.append(
+                        self.signal_ax[idx + 1].text(
+                            x=x, y=-y_lim + y_shift, s="S", color="lime"))
+                if i == 1:
+                    self.signal_start_end_axvline.append(
+                        self.signal_ax[idx + 1].text(
+                            x=x, y=-y_lim + y_shift,
+                            horizontalalignment="right", s="E", color="lime"))
+
+        if flush:
+            self.signal_figure.canvas.draw()
+            self.signal_figure.canvas.flush_events()
+            self.plot_hypo()
+
+    def plot_marker_line(self, flush=True):
+        """Plot marker lines in the signal area."""
+        marker_color = self.config["gui"].get(
+            "markerlinecolor", "red").strip("\"'")
+        for axvline in self.signal_marker_axvline:
+            try:
+                axvline.remove()
+            except Exception:
+                pass
+        self.signal_marker_axvline = []
+        for each in self.mianno.marker:
+            if self.current_sec <= each[0] <= self.current_sec + self.show_duration:
+                for idx, show_ in enumerate(self.show_idx):
+                    self.signal_marker_axvline.append(
+                        self.signal_ax[idx + 1].axvline(
+                            int((each[0] - self.current_sec) * self.midata.sf[show_]),
+                            color=marker_color, alpha=1))
+                self.signal_marker_axvline.append(
+                    self.signal_ax[1].text(
+                        x=int((each[0] - self.current_sec) * self.midata.sf[self.show_idx[0]]),
+                        y=self.y_lims[self.show_idx[0]] + self.y_shift[self.show_idx[0]],
+                        s=each[1], verticalalignment="top", color=marker_color))
+
+        if flush:
+            self.signal_figure.canvas.draw()
+            self.signal_figure.canvas.flush_events()
+            self.plot_hypo()
+
+    def plot_start_end_label_line(self, flush=True):
+        """Plot the start/end annotation label lines."""
+        for art in getattr(self, "signal_se_label_axvline", []):
+            try:
+                art.remove()
+            except Exception:
+                pass
+        self.signal_se_label_axvline = []
+        for each in self.mianno.start_end:
+            if self.current_sec <= each[0] <= self.current_sec + self.show_duration:
+                for idx, show_ in enumerate(self.show_idx):
+                    self.signal_se_label_axvline.append(
+                        self.signal_ax[idx + 1].axvline(
+                            int((each[0] - self.current_sec) * self.midata.sf[show_]),
+                            color=identify_startend_color(self.start_end_color_dict, each[2]),
+                            alpha=1))
+                self.signal_se_label_axvline.append(
+                    self.signal_ax[1].text(
+                        x=int((each[0] - self.current_sec) * self.midata.sf[self.show_idx[0]]),
+                        y=self.y_lims[self.show_idx[0]] + self.y_shift[self.show_idx[0]],
+                        s=each[2] + "-S", verticalalignment="top",
+                        color=identify_startend_color(self.start_end_color_dict, each[2])))
+
+            if self.current_sec <= each[1] <= self.current_sec + self.show_duration:
+                for idx, show_ in enumerate(self.show_idx):
+                    self.signal_se_label_axvline.append(
+                        self.signal_ax[idx + 1].axvline(
+                            int((each[1] - self.current_sec) * self.midata.sf[show_]),
+                            color="orange", alpha=1))
+                self.signal_se_label_axvline.append(
+                    self.signal_ax[1].text(
+                        x=int((each[1] - self.current_sec) * self.midata.sf[self.show_idx[0]]),
+                        y=self.y_lims[self.show_idx[0]] + self.y_shift[self.show_idx[0]],
+                        s=each[2] + "-E", verticalalignment="top",
+                        horizontalalignment="right", color="orange"))
+
+        if flush:
+            self.signal_figure.canvas.draw()
+            self.signal_figure.canvas.flush_events()
+
+    def plot_horizontal_line(self, flush=True):
+        """Plot the horizontal reference lines."""
+        for axhline in self.axhline_horizontal:
+            try:
+                axhline.remove()
+            except Exception:
+                pass
+        for idx, show_ in enumerate(self.show_idx):
+            ch = self.midata.channels[show_]
+            sf = self.midata.sf[show_]
+            for line_value, color, comment in self.horizontal_line.get(ch, []):
+                self.axhline_horizontal.append(
+                    self.signal_ax[idx + 1].axhline(line_value, color=color, alpha=1))
+                self.axhline_horizontal.append(
+                    self.signal_ax[idx + 1].text(
+                        x=int(self.show_duration * sf), y=line_value,
+                        s=f"{line_value:.2e}",
+                        horizontalalignment="left", color=color))
+
+        if flush:
+            self.signal_figure.canvas.draw()
+            self.signal_figure.canvas.flush_events()
+
+    def plot_hypo(self):
+        """Redraw the hypnogram area (one colored segment per sleep state)."""
+        # The state-step background only changes when the annotation changes;
+        # rebuild it lazily and reuse it across page flips.
+        key = None
+        if self.mianno is not None:
+            key = (
+                id(self.mianno),
+                self._hypo_revision,
+                tuple(sorted(self.state_map_dict.items())),
+                tuple(sorted(self.state_color_dict.items())),
+                float(self.config["gui"].get("hypnogramstatealpha", "0.55")),
+            )
+        if key != self._hypo_key:
+            self.hypo_ax.clear()
+            self._hypo_transient = []
+            # One thick filled bar per consecutive run of the same state,
+            # spanning the full state band (edges touch between states).
+            # All bars are drawn as a single PolyCollection, so building the
+            # hypnogram stays fast even for multi-hour recordings with tens
+            # of thousands of state runs.
+            band = 0.5  # half height of each bar (state +/- band)
+            runs = lst2group([i, each] for i, each in enumerate(self.mianno.sleep_state))
+            rects = []
+            colors = []
+            for start, end, state in runs:
+                if end <= start:
+                    continue
+                y0 = state - band
+                y1 = state + band
+                rects.append([(start, y0), (end, y0), (end, y1), (start, y1)])
+                colors.append(self.state_color_dict.get(state, "#8892a0"))
+            if rects:
+                collection = PolyCollection(
+                    rects, facecolors=colors, edgecolors="none",
+                    alpha=float(self.config["gui"].get(
+                        "hypnogramstatealpha", "0.55")), zorder=1)
+                self._hypo_steps.append(self.hypo_ax.add_collection(collection))
+
+            self.hypo_ax.set_ylim(0, len(list(self.state_map_dict.keys())) + 0.5)
+            self.hypo_ax.set_xlim(0, self.total_seconds)
+            self.hypo_ax.yaxis.set_ticks(
+                list(self.state_map_dict.keys()), list(self.state_map_dict.values()))
+            self.hypo_ax.set_xlabel("Time (s)")
+            # faint horizontal guides at each state level
+            self.hypo_ax.grid(axis="y", alpha=0.25)
+            self._hypo_key = key
+
+        # remove the per-flip overlay artists (current-time / event lines)
+        for art in self._hypo_transient:
+            try:
+                art.remove()
+            except Exception:
+                pass
+        self._hypo_transient = []
+
+        try:
+            self.hypo_axvline.remove()
+        except Exception:
+            pass  # axes may have been recreated; a new line is drawn below
+        self.hypo_axvline = self.hypo_ax.axvline(
+            self.current_sec, color="gray", alpha=0.8)
+        self._hypo_transient.append(self.hypo_axvline)
+
+        if self.StartEndRadio.isChecked():
+            for each in self.start_end_ms:
+                self._hypo_transient.append(
+                    self.hypo_ax.axvline(each, color="lime", alpha=1))
+        if self.SleepStateRadio.isChecked():
+            for each in self.start_end:
+                self._hypo_transient.append(
+                    self.hypo_ax.axvline(each, color="lime", alpha=1))
+        for each in self.mianno.marker:
+            self._hypo_transient.append(
+                self.hypo_ax.axvline(
+                    each[0], color=self.config["gui"].get(
+                        "markerlinecolor", "red").strip("\"'"), alpha=1,
+                    linewidth=1.6, zorder=6))
+
+        self.hypo_figure.canvas.draw()
+        self.hypo_figure.canvas.flush_events()
+
+    def redraw_all(self, second=0):
+        """Validate ``second`` and redraw everything."""
+        # heal the canvases first in case an export closed a figure
+        self._repair_canvases()
+
+        if second + self.show_duration >= self.total_seconds:
+            self.current_sec = self.total_seconds - self.show_duration
+        elif second <= 0:
+            self.current_sec = 0
+        else:
+            self.current_sec = second
+
+        # Block signals to avoid cyclic value-change operations
+        self.ScrollerBar.blockSignals(True)
+        self.SecondSpin.blockSignals(True)
+        self.DateTimeEdit.blockSignals(True)
+        self.ScrollerBar.setValue(self.current_sec)
+        self.SecondSpin.setValue(self.current_sec)
+        self.DateTimeEdit.setDateTime(self.ac_time + datetime.timedelta(seconds=self.current_sec))
+        self.ScrollerBar.blockSignals(False)
+        self.SecondSpin.blockSignals(False)
+        self.DateTimeEdit.blockSignals(False)
+        self.plot_signals()
+        self.plot_hypo()
+
+    def fill_channel_listView(self):
+        """Fill the channel list view with ``self.midata.channels``."""
+        self._updating_ch_list = True
+        try:
+            self.channel_slm.setChannels(self.midata.channels)
+            # only (re)attach the model when needed, otherwise the
+            # selection would be cleared on every refresh
+            if self.ChListView.model() is not self.channel_slm:
+                self.ChListView.setModel(self.channel_slm)
+                selection_model = self.ChListView.selectionModel()
+                if selection_model is not None:
+                    selection_model.selectionChanged.connect(
+                        self._update_channel_action_states)
+        finally:
+            self._updating_ch_list = False
+        self._update_channel_action_states()
+
+    def _on_channel_list_changed(self, *args):
+        """React to any channel-list model change.
+
+        ``ChannelListModel`` supports ``moveRows``, so a drag & drop emits
+        ``rowsMoved``; this hook detects the resulting pure reorder (a
+        permutation of the channel names) and applies it. Plain text edits
+        are left to :meth:`channel_rename`.
+        """
+        if self._updating_ch_list or self.midata is None:
+            return
+        try:
+            lst = list(self.channel_slm.channels())
+        except Exception:
+            return
+        if len(lst) != self.midata.n_channels:
+            return
+        if lst == self.midata.channels:
+            return
+        if sorted(lst) != sorted(self.midata.channels):
+            return  # a text edit (rename), not a move
+        self.channel_moved(None, 0, len(lst) - 1, None, 0)
+
+    def _apply_channel_order(self, new_order):
+        """Reorder the data and view state to match ``new_order``.
+
+        Only the order changes -- channel names and data stay intact.
+        """
+        spec_name = self.midata.channels[self.current_spectrogram_idx]
+        order_idx = [self.midata.channels.index(name) for name in new_order]
+
+        self.midata.reorder_channels(new_order)
+
+        self.y_lims = [self.y_lims[i] for i in order_idx]
+        self.y_shift = [self.y_shift[i] for i in order_idx]
+        self.horizontal_line = {name: self.horizontal_line.get(name, []) for name in new_order}
+        self.current_spectrogram_idx = self.midata.channels.index(spec_name)
+        self.show_idx = list(range(self.midata.n_channels))
+
+        self.fill_channel_listView()
+        self.redraw_all(second=self.current_sec)
+
+    def channel_moved(self, parent, start, end, destination, row):
+        """Reorder the data to match a model move in the channel list."""
+        if self._updating_ch_list or self.midata is None:
+            return
+
+        new_order = list(self.channel_slm.channels())
+        if new_order == self.midata.channels or len(new_order) != self.midata.n_channels:
+            return
+        self._apply_channel_order(new_order)
+
+    def move_channel(self, direction):
+        """Move the selected channel up or down in the list (buttons)."""
+        if self.midata is None:
+            return
+        selected = [r.row() for r in self.ChListView.selectedIndexes()]
+        if len(selected) != 1:
+            return
+        row = selected[0]
+        target = row - 1 if direction == "up" else row + 1
+        if not (0 <= target < self.midata.n_channels):
+            return
+
+        order = list(self.midata.channels)
+        item = order.pop(row)
+        order.insert(target, item)
+        self._apply_channel_order(order)
+
+        # keep the moved item selected (get a fresh selection model --
+        # setModel may have recreated it)
+        sm = self.ChListView.selectionModel()
+        idx = self.channel_slm.index(target)
+        self.ChListView.setCurrentIndex(idx)
+        if sm is not None:
+            sm.select(idx, sm.SelectionFlag.ClearAndSelect)
+        self._update_channel_action_states()
+
+    def show_marker_list(self):
+        """Open the marker list viewer dialog."""
+        if self.mianno is None:
+            QMessageBox.about(self, "Info", "Load data and annotation first.")
+            return
+        dialog = EventListDialog(self)
+        dialog.show_events(kind="marker")
+        dialog.exec()
+
+    def show_start_end_list(self):
+        """Open the start-end event list viewer dialog."""
+        if self.mianno is None:
+            QMessageBox.about(self, "Info", "Load data and annotation first.")
+            return
+        dialog = EventListDialog(self)
+        dialog.show_events(kind="start_end")
+        dialog.exec()
+
+    def _sync_state_buttons(self):
+        """Keep the Annotation dock state buttons in sync with the state map.
+
+        Every configured state lives in the same two-column grid.  The four
+        original buttons are reused; additional states are created there too.
+        """
+        orig = {1: self.NREMBt, 2: self.REMBt, 3: self.WakeBt, 4: self.InitBt}
+        self._state_btns = {}
+        for bt in orig.values():
+            bt.hide()
+
+        # clear and (re)fill the shared state grid
+        extra_grid = self.ExtraStatePanel.layout()
+        while extra_grid.count():
+            item = extra_grid.takeAt(0)
+            w = item.widget()
+            if w is not None and w not in orig.values():
+                w.deleteLater()
+
+        for button_idx, code in enumerate(sorted(self.state_map_dict)):
+            name = self.state_map_dict[code]
+            color = self.state_color_dict.get(code, "#808080")
+            if code in orig:
+                bt = orig[code]
+                bt.show()
+            else:
+                bt = QPushButton()
+                bt.clicked.connect(
+                    lambda _=False, c=code: self.sleep_state_label(state_code=c))
+            row, col = divmod(button_idx, 2)
+            extra_grid.addWidget(bt, row, col)
+            bt.setSizePolicy(QSizePolicy.Policy.Expanding,
+                             QSizePolicy.Policy.Fixed)
+            bt.setText(f"{code}:{name}")
+            # Full local style: readable text on any state color (works in
+            # light and dark themes - e.g. a white 'Init' button needs dark
+            # text, and a dark state color needs white text).
+            fg = _text_on(color)
+            bt.setStyleSheet(
+                f"QPushButton {{ background-color: {color}; color: {fg};"
+                f" border: 1px solid rgba(0,0,0,150); border-radius: 3px;"
+                f" padding: 2px 7px; min-height: 19px; max-height: 22px;"
+                f" font-weight: 600; }}"
+                f" QPushButton:hover {{ border: 1px solid rgba(255,255,255,190); }}"
+                f" QPushButton:pressed {{ background-color: {color}; }}"
+                f" QPushButton:disabled {{ background-color: #9aa3af;"
+                f" color: #dce1e8; border-color: #7d8794; }}")
+            bt.setToolTip(
+                f"Label the selected area as {name} "
+                f"(shortcut key {code if code < 10 else 0})")
+            self._state_btns[code] = bt
+        extra_grid.setColumnStretch(0, 1)
+        extra_grid.setColumnStretch(1, 1)
+        self._update_annotation_mode()
+
+    # ------------------------------------------------------------------
+    # Interaction
+    # ------------------------------------------------------------------
+    def radio_recheck(self, radioBt):
+        """Reset the selection lines when the label mode changes."""
+        if not radioBt.isChecked():
+            return
+        if radioBt is self.SleepStateRadio:
+            self.start_end_ms = []
+            self.plot_start_end_line()
+        if radioBt is self.StartEndRadio:
+            self.start_end = []
+            self.plot_start_end_line(ms=True)
+        self._update_annotation_mode()
+
+    def click_signal(self, event):
+        """Handle clicks in the signal area (marker / start-end selection).
+
+        The clicked axes identifies the channel (row ``i`` of the signal
+        boxes); the x position gives the time.
+        """
+        if event.inaxes == self.signal_ax[0]:
+            return
+
+        # Find the channel row by identity (Axes are not compared by value)
+        row = None
+        for idx, ax in enumerate(self.signal_ax):
+            if ax is event.inaxes:
+                row = idx - 1
+                break
+        if row is None or row < 0 or row >= len(self.show_idx):
+            return
+
+        try:
+            sf = self.midata.sf[self.show_idx[row]]
+            sec = int(event.xdata / sf) + self.current_sec
+        except (TypeError, IndexError):
+            return
+
+        if self.SleepStateRadio.isChecked():
+            if event.button == 3:
+                # Right click: remove the line(s) at this second
+                for each in self.mianno.start_end:
+                    if each[0] == sec or each[1] == sec:
+                        self.mianno.start_end.remove(each)
+                        self.plot_signals()
+                        return
+                if len(self.start_end) == 0:
+                    return
+                if len(self.start_end) >= 1 and sec == self.start_end[0]:
+                    self.start_end = []
+                    self.plot_start_end_line()
+                    return
+                if len(self.start_end) == 2 and sec + 1 == self.start_end[1]:
+                    self.start_end.pop(1)
+                    self.plot_start_end_line()
+                    return
+                return
+
+            if not self.start_end:
+                self.start_end.append(sec)
+            elif len(self.start_end) == 2:
+                self.start_end = [sec]
+            elif sec < self.start_end[0]:
+                self.start_end = [sec]
+            else:
+                self.start_end.append(sec + 1)
+
+            self.plot_start_end_line()
+
+        if self.MarkerRadio.isChecked():
+            if event.button == 3:
+                for each in self.mianno.marker:
+                    if abs(each[0] - sec) <= 1:
+                        self.mianno.marker.remove(each)
+                self.plot_signals()
+                self.plot_hypo()
+                return
+
+            x = round(event.xdata / sf, 3) + self.current_sec
+
+            self.label_dialog._type = 0
+            self.label_dialog.show_contents()
+            self.label_dialog.exec()
+            if self.label_dialog.closed:
+                return
+
+            label_name = self.label_dialog.label_name
+            self.mianno.marker.append([x, label_name])
+            self.plot_marker_line()
+
+            self.is_saved = False
+            self.AnnotationPathLabel.setText("*Annotation path:")
+
+        if self.StartEndRadio.isChecked():
+            x = round(event.xdata / sf, 3) + self.current_sec
+            if event.button == 3:
+                for each in self.mianno.start_end:
+                    if int(each[0]) == sec or int(each[1]) == sec:
+                        self.mianno.start_end.remove(each)
+                        self.plot_signals()
+                        return
+                if len(self.start_end_ms) == 0:
+                    return
+                if len(self.start_end_ms) >= 1 and sec == int(self.start_end_ms[0]):
+                    self.start_end_ms = []
+                    self.plot_start_end_line(ms=True)
+                    return
+                if len(self.start_end_ms) == 2 and sec == int(self.start_end_ms[1]):
+                    self.start_end_ms.pop(1)
+                    self.plot_start_end_line(ms=True)
+                    return
+                return
+
+            if not self.start_end_ms:
+                self.start_end_ms.append(x)
+            elif len(self.start_end_ms) == 2:
+                if abs(x - self.start_end_ms[1]) <= 1:
+                    self.start_end_ms[0] = self.start_end_ms[1]
+                    self.start_end_ms.pop(1)
+                else:
+                    self.start_end_ms = [x]
+            else:
+                if x < self.start_end_ms[0]:
+                    QMessageBox.about(self, "Error", "End should be larger than Start!")
+                    return
+                self.start_end_ms.append(x)
+
+            self.plot_start_end_line(ms=True)
+            if len(self.start_end_ms) == 2:
+                # Leave the matplotlib callback first, then open the modal
+                # label chooser.  This avoids a half-painted selection line.
+                QTimer.singleShot(0, self.append_start_end)
+
+    def click_hypo(self, event):
+        """Jump to the clicked time on the hypnogram."""
+        if event.inaxes is not self.hypo_ax or event.xdata is None:
+            return
+        current_sec = int(event.xdata)
+        self.redraw_all(second=current_sec)
+
+    def scroller_change(self):
+        """Scrollbar value changed."""
+        self.ScrollerBar.setDisabled(True)
+        current_sec = self.ScrollerBar.value()
+        self.redraw_all(second=current_sec)
+        self.ScrollerBar.setEnabled(True)
+
+    def next_epoch(self):
+        self.redraw_all(second=self.current_sec + 5)
+
+    def previous_epoch(self):
+        self.redraw_all(second=self.current_sec - 5)
+
+    def next_page(self):
+        self.redraw_all(second=self.current_sec + self.show_duration)
+
+    def previous_page(self):
+        self.redraw_all(second=self.current_sec - self.show_duration)
+
+    def SecondSpin_change(self):
+        self.redraw_all(second=self.SecondSpin.value())
+
+    def DateTimeEdit_change(self):
+        dateTime = self.DateTimeEdit.dateTime().toPython()
+        current_sec = int((dateTime - self.ac_time).total_seconds())
+        self.redraw_all(second=current_sec)
+
+    # ------------------------------------------------------------------
+    # Channel operations
+    # ------------------------------------------------------------------
+    def channel_rename(self):
+        """Rename channels from the list view.
+
+        A pure reorder (a permutation of the names) is not a rename -- it
+        is handled by :meth:`_on_channel_list_changed` / :meth:`channel_moved`.
+        """
+        new_channels = list(self.channel_slm.channels())
+        if sorted(new_channels) == sorted(self.midata.channels):
+            return  # drag & drop reorder, not a rename
+
+        old_channels = list(self.midata.channels)
+        rename_map = {}
+        for old, new in zip(old_channels, new_channels):
+            if old != new:
+                rename_map[old] = new
+        if not rename_map:
+            return
+
+        # rename_channels may add a "_1" suffix when the target name is
+        # already in use, so rebuild horizontal_line by position afterwards.
+        self.midata.rename_channels(rename_map)
+        final_channels = self.midata.channels
+        self.horizontal_line = {
+            final_channels[i]: self.horizontal_line.get(old_channels[i], [])
+            for i in range(len(final_channels))
+        }
+
+        self.fill_channel_listView()
+        self.plot_signals()
+
+    def show_chs(self):
+        """Show the selected channels."""
+        selected_channels = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channels:
+            return
+        self.show_idx = sorted(selected_channels)
+        self.plot_signals()
+
+    def hide_chs(self):
+        """Hide the selected channels."""
+        selected_channels = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channels:
+            return
+        all_channels = copy.deepcopy(self.show_idx)
+        for each in selected_channels:
+            if each in all_channels:
+                all_channels.remove(each)
+
+        if not all_channels:
+            QMessageBox.about(self, "Error", "You can't hide all channels!")
+            return
+
+        self.show_idx = all_channels
+        self.plot_signals()
+
+    def delete_chs(self):
+        """Delete the selected channels from the data."""
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channel:
+            return
+        box = QMessageBox.question(
+            self, "Warning", "You are deleting data!",
+            QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
+            QMessageBox.StandardButton.No)
+
+        if box == QMessageBox.StandardButton.Yes:
+            if len(selected_channel) == self.midata.n_channels:
+                QMessageBox.about(self, "Error", "You can't delete all channels!")
+                return
+
+            spec_name = self.midata.channels[self.current_spectrogram_idx]
+            for each in sorted(selected_channel, reverse=True):
+                self.y_lims[each] = -1
+                self.y_shift[each] = -1
+                self.horizontal_line.pop(self.midata.channels[each], None)
+                self.midata.delete(self.midata.channels[each])
+
+            self.y_lims = [each for each in self.y_lims if each != -1]
+            self.y_shift = [each for each in self.y_shift if each != -1]
+            if spec_name in self.midata.channels:
+                self.current_spectrogram_idx = self.midata.channels.index(spec_name)
+            else:
+                self.current_spectrogram_idx = 0
+
+            self.show_idx = list(range(self.midata.n_channels))
+            self.fill_channel_listView()
+            self.redraw_all(second=self.current_sec)
+
+    def scaler_up(self):
+        """Zoom in on the selected channels."""
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channel:
+            return
+        self.y_lims = [
+            lim * 0.9 if idx in selected_channel else lim
+            for idx, lim in enumerate(self.y_lims)]
+        self.plot_signals(clf=False, replot_axes=selected_channel)
+
+    def scaler_down(self):
+        """Zoom out on the selected channels."""
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channel:
+            return
+        self.y_lims = [
+            lim * 1.1 if idx in selected_channel else lim
+            for idx, lim in enumerate(self.y_lims)]
+        self.plot_signals(clf=False, replot_axes=selected_channel)
+
+    def multiple_scaler(self):
+        """Scale the selected channels by a custom factor."""
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        scaler_num = self.multipleScalerEditor.value()
+        if not selected_channel:
+            return
+        self.y_lims = [
+            lim / scaler_num if idx in selected_channel else lim
+            for idx, lim in enumerate(self.y_lims)]
+        self.plot_signals(clf=False, replot_axes=selected_channel)
+
+    def shift_up(self):
+        """Shift the selected channels up."""
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channel:
+            return
+        self.y_shift = [
+            shift - self.y_lims[idx] * 0.05 if idx in selected_channel else shift
+            for idx, shift in enumerate(self.y_shift)]
+        self.plot_signals(clf=False, replot_axes=selected_channel)
+
+    def shift_down(self):
+        """Shift the selected channels down."""
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channel:
+            return
+        self.y_shift = [
+            shift + self.y_lims[idx] * 0.05 if idx in selected_channel else shift
+            for idx, shift in enumerate(self.y_shift)]
+        self.plot_signals(clf=False, replot_axes=selected_channel)
+
+    def filter_confirm(self):
+        """Apply a filter to the selected channel."""
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channel:
+            return
+        if len(selected_channel) > 1:
+            QMessageBox.about(
+                self, "Error",
+                "Select one channel to be the default channel for spectrogram.")
+            return
+
+        filter_type = self.FilterTypeCombo_dict[self.FilterTypeCombo.currentIndex()]
+        low = self.FilterLowSpin.value()
+        high = self.FilterHighSpin.value()
+        if filter_type in ("bandpass", "bandstop") and low >= high:
+            return
+        self.midata.filter(
+            chans=[self.midata.channels[selected_channel[0]]],
+            btype=filter_type, low=low, high=high)
+        self.y_lims.append(self.y_lims[selected_channel[0]])
+        self.y_shift.append(self.y_shift[selected_channel[0]])
+
+        self.horizontal_line[self.midata.channels[-1]] = []
+        self.show_idx.append(self.midata.n_channels - 1)
+        self.fill_channel_listView()
+        self.redraw_all(second=self.current_sec)
+
+    def FilterTypeCombo_change(self):
+        """Enable/disable the filter cut-off spins according to the filter type."""
+        if self.FilterTypeCombo.currentIndex() in (0, 3):
+            self.FilterHighSpin.setEnabled(True)
+            self.FilterLowSpin.setEnabled(True)
+        if self.FilterTypeCombo.currentIndex() == 1:
+            self.FilterHighSpin.setDisabled(True)
+            self.FilterLowSpin.setEnabled(True)
+        if self.FilterTypeCombo.currentIndex() == 2:
+            self.FilterHighSpin.setEnabled(True)
+            self.FilterLowSpin.setDisabled(True)
+
+    def show_spec_window(self):
+        """Show the spectrum/spectrogram window for the selected segment."""
+        from misleep.gui.spec_window import SpecWindow
+        from misleep.preprocessing.spectral import band_power, spectrogram, spectrum
+
+        if self.SleepStateRadio.isChecked() and len(self.start_end) == 2 and \
+                self.start_end[1] - self.start_end[0] >= 5:
+            start_ = self.start_end[0]
+            end_ = self.start_end[1]
+        elif self.StartEndRadio.isChecked() and len(self.start_end_ms) == 2 and \
+                self.start_end_ms[1] - self.start_end_ms[0] >= 5:
+            start_ = self.start_end_ms[0]
+            end_ = self.start_end_ms[1]
+        else:
+            QMessageBox.about(
+                self, "Error",
+                "Please select a start-end larger than 5 seconds.")
+            return
+
+        selected_channel = [each.row() for each in self.ChListView.selectedIndexes()]
+        if not selected_channel or len(selected_channel) > 1:
+            QMessageBox.about(
+                self, "Error",
+                "Select one channel to show spectral analysis")
+            return
+
+        channel = selected_channel[0]
+        signal_data = self.midata.signals[channel][
+            int(start_ * self.midata.sf[channel]): int(end_ * self.midata.sf[channel])]
+
+        win_sec = int(float(self.config["spec"]["win_length_sec"]))
+        nfft = int(float(self.config["spec"]["nfft_sec"]) * self.midata.sf[channel])
+        if win_sec > (end_ - start_):
+            win_sec = end_ - start_
+        if nfft < int(win_sec * self.midata.sf[channel]):
+            nfft = int(win_sec * self.midata.sf[channel])
+
+        try:
+            spec_window = self._ensure_dialog("spec_window", SpecWindow)
+            freq_range = [float(x) for x in self.config["gui"]["freq_range"].strip("[]").split(",")]
+            freq, psd = spectrum(
+                signal=signal_data,
+                sf=self.midata.sf[channel],
+                band=freq_range,
+                nfft=nfft,
+                gaussian_sigma=float(self.config["spec"]["gaussian_sigma"]),
+                win_sec=win_sec,
+                relative=False)
+
+            f, t, Sxx = spectrogram(
+                signal=signal_data,
+                sf=self.midata.sf[channel],
+                band=freq_range,
+                step=1, win_sec=win_sec, norm=False, nfft=nfft)
+
+            bandPower = band_power(psd=psd, freq=freq,
+                                   bands=[[0.5, 4, "delta"], [4, 9, "theta"]])
+            ratio = bandPower["delta"] / bandPower["theta"]
+
+            spec_window.show_(
+                spectrum=[psd, freq],
+                spectrogram=[f, t, Sxx],
+                percentile_=self.spectrogram_percentile,
+                ratio=ratio, start_end=[start_, end_],
+                freq_range=freq_range,
+                data_path=self.data_path)
+
+            spec_window.activateWindow()
+            state = spec_window.windowState()
+            spec_window.setWindowState(
+                (state & ~Qt.WindowState.WindowMinimized)
+                | Qt.WindowState.WindowActive)
+            spec_window.showNormal()
+        except Exception:
+            QMessageBox.about(
+                self, "Error",
+                "An error occurred while generating the spectral analysis.")
+            return
+
+    def set_show_duration(self, type_="Combo"):
+        """Set the show duration from the combo box or the custom spin box."""
+        if type_ == "Combo":
+            selected_idx = self.ShowRangeCombo.currentIndex()
+            if self.ShowRangeCombo_dict[selected_idx] + self.current_sec >= self.total_seconds:
+                self.show_duration = 30
+                self.current_sec = 0
+                self.ShowRangeCombo.setCurrentIndex(0)
+            else:
+                self.show_duration = self.ShowRangeCombo_dict[selected_idx]
+        if type_ == "Spin":
+            show_duration = self.SecondNumSpin.value()
+            if show_duration + self.current_sec >= self.total_seconds:
+                self.show_duration = 30
+                self.current_sec = 0
+                self.SecondNumSpin.setValue(30)
+            else:
+                self.show_duration = show_duration
+
+        self.reset_sec_limit()
+        self.redraw_all(second=self.current_sec)
+        self.ScrollerBar.setPageStep(self.show_duration)
+
+    def CustomSecondCheck_clicked(self):
+        if self.CustomSecondsCheck.isChecked():
+            self.ShowRangeCombo.setDisabled(True)
+            self.SecondNumSpin.setEnabled(True)
+            self.set_show_duration(type_="Spin")
+        else:
+            self.ShowRangeCombo.setEnabled(True)
+            self.SecondNumSpin.setDisabled(True)
+            self.set_show_duration(type_="Combo")
+
+    def ShowRangeCombo_changed(self):
+        self.set_show_duration(type_="Combo")
+
+    def SecondNumSpin_changed(self):
+        self.set_show_duration(type_="Spin")
+
+    # ------------------------------------------------------------------
+    # Labeling
+    # ------------------------------------------------------------------
+    def nrem_label(self):
+        self.append_sleep_state(sleep_type=1)
+
+    def rem_label(self):
+        self.append_sleep_state(sleep_type=2)
+
+    def wake_label(self):
+        self.append_sleep_state(sleep_type=3)
+
+    def init_label(self):
+        self.append_sleep_state(sleep_type=4)
+
+    def sleep_state_label(self, state_code=1):
+        """Label the selected area with a custom state code (from config)."""
+        self.append_sleep_state(sleep_type=state_code)
+
+    def append_sleep_state(self, sleep_type=None):
+        """Assign a sleep state to the selected start-end area."""
+        if len(self.start_end) != 2:
+            QMessageBox.about(
+                self, "Info", "Please select a start end area in Sleep state mode")
+            return
+
+        self.mianno.sleep_state[self.start_end[0]: self.start_end[1]] = \
+            [sleep_type] * (self.start_end[1] - self.start_end[0])
+        self._hypo_revision += 1
+
+        self.is_saved = False
+        self.AnnotationPathLabel.setText("*Annotation path:")
+        self.replot_sleep_state_bg(state=sleep_type)
+        self.plot_hypo()
+
+    def append_start_end(self):
+        """Append a start-end label to the annotation."""
+        if not self.StartEndRadio.isChecked():
+            QMessageBox.about(self, "Info", "Use Start-End mode")
+            return
+        if len(self.start_end_ms) != 2:
+            QMessageBox.about(self, "Info", "Please select a start end area")
+            return
+
+        self.label_dialog._type = 1
+        self.label_dialog.show_contents()
+        self.label_dialog.exec()
+        if self.label_dialog.closed:
+            return
+
+        label_name = self.label_dialog.label_name
+        self.mianno.start_end.append(
+            [self.start_end_ms[0], self.start_end_ms[1], label_name])
+        self.plot_start_end_label_line()
+
+        self.is_saved = False
+        self.AnnotationPathLabel.setText("*Annotation path:")
+
+    # ------------------------------------------------------------------
+    # Tools / analysis
+    # ------------------------------------------------------------------
+    def transfer_result(self):
+        """Transfer the annotation into an Excel result file."""
+        dialog = self._ensure_dialog(
+            "transfer_result_dialog", TransferResultDialog)
+        dialog.ACTimeEditor.setDateTime(self.ac_time)
+        dialog.TransferStartTimeEdit.setDateTime(self.ac_time)
+        dialog.exec()
+        if dialog.closed:
+            return
+        try:
+            with self._busy_operation():
+                saved = dialog.transfer(
+                    config=self.config, mianno=self.mianno,
+                    ac_time=self.midata.time)
+        except Exception as exc:
+            logger.exception("Transfer result failed")
+            QMessageBox.about(self, "Error", f"Transfer result failed: {exc}")
+            return
+        if saved:
+            QMessageBox.about(self, "Info", "Transferred result saved")
+
+    def state_spectral(self):
+        """Run the per-state spectral analysis."""
+        dialog = self._ensure_dialog(
+            "state_spectral_dialog", lambda: StateSpectralDialog(config=self.config))
+        dialog.StartTimeEditor.setDateTime(self.ac_time)
+        dialog.EndTimeEditor.setDateTime(
+            self.ac_time + datetime.timedelta(seconds=self.total_seconds))
+        dialog.dialog_show(channels=self.midata.channels)
+        dialog.exec()
+        if dialog.closed:
+            return
+        try:
+            with self._busy_operation():
+                saved = dialog.spectral_analysis(
+                    midata=self.midata, mianno=self.mianno,
+                    config=self.config)
+        except Exception as exc:
+            logger.exception("State spectral export failed")
+            QMessageBox.about(self, "Error", f"Spectral export failed: {exc}")
+            return
+        if saved:
+            QMessageBox.about(self, "Info", "Spectral analysis finished")
+
+    def add_horizontal_line(self):
+        """Add a horizontal reference line."""
+        try:
+            dialog = self._ensure_dialog(
+                "horizontal_line_dialog", HorizontalLineDialog)
+            dialog.horizontal_line = copy.deepcopy(self.horizontal_line)
+            dialog.show_chs()
+            dialog.midata = self.midata
+            dialog.exec()
+            if dialog.closed:
+                return
+            self.horizontal_line = dialog.horizontal_line
+            self.plot_horizontal_line()
+        except Exception as e:
+            logger.error(f"Add horizontal line ERROR: {e}")
+            QMessageBox.about(self, "Error", str(e))
+            return
+
+    def swa_detection(self):
+        """Slow-wave activity detection."""
+        try:
+            dialog = self._ensure_dialog(
+                "swa_detection_dialog", SWADetectionDialog)
+            dialog.show_chs(self.midata.channels)
+            dialog.exec()
+            if dialog.closed:
+                return
+            swa_lst = dialog.swa_detection(
+                self.midata, self.mianno, self.config)
+
+            self.mianno._start_end += [[each[0], each[4], "SWA"] for each in swa_lst]
+            self.plot_start_end_label_line()
+            self.is_saved = False
+            self.AnnotationPathLabel.setText("*Annotation path:")
+        except Exception as e:
+            logger.error(f"SWA_detection ERROR: {e}")
+            QMessageBox.about(self, "Error", f"SWA detection ERROR. {e}")
+            return
+
+    def spindle_detection(self):
+        """Sleep spindle detection."""
+        try:
+            dialog = self._ensure_dialog(
+                "spindel_detection_dialog", SpindleDetectionDialog)
+            dialog.show_chs(self.midata.channels)
+            dialog.exec()
+            if dialog.closed:
+                return
+            spindle_lst = dialog.spindle_detection(
+                self.midata, self.mianno, self.config)
+
+            self.mianno._start_end += [[each[0], each[1], "Spindle"] for each in spindle_lst]
+            self.plot_start_end_label_line()
+            self.is_saved = False
+            self.AnnotationPathLabel.setText("*Annotation path:")
+        except Exception as e:
+            logger.error(f"Spindel_detection ERROR: {e}")
+            QMessageBox.about(self, "Error", "Spindle detection ERROR")
+            return
+
+    def auto_stage_LightGBM(self):
+        """Auto stage with the LightGBM model."""
+        try:
+            dialog = self._ensure_dialog(
+                "auto_stage_lightGBM_dialog", AutoStageLightGBMDialog)
+            dialog.show_chs(self.midata.channels)
+            dialog.exec()
+            if dialog.closed:
+                return
+            auto_stage_lst, save_anno = dialog.auto_stage(
+                self.midata, self.mianno)
+
+            limit = min(len(self.mianno._sleep_state), len(auto_stage_lst))
+            self.mianno._sleep_state[:limit] = auto_stage_lst[:limit]
+            self._hypo_revision += 1
+
+            if save_anno:
+                self.save_anno()
+            self.is_saved = False
+            self.AnnotationPathLabel.setText("*Annotation path:")
+            self.plot_signals()
+            self.plot_hypo()
+        except ImportError as e:
+            QMessageBox.about(self, "Error", str(e))
+            return
+        except Exception as e:
+            logger.error(f"Auto stage ERROR: {e}")
+            QMessageBox.about(self, "Error", "Auto stage ERROR")
+            return
+
+    def auto_stage_CausalTransformer(self):
+        """Auto stage with the causal-transformer model."""
+        try:
+            dialog = self._ensure_dialog(
+                "auto_stage_causalTransformer_dialog",
+                AutoStageCausalTransformerDialog)
+            dialog.show_chs(self.midata.channels)
+            dialog.exec()
+            if dialog.closed:
+                return
+            auto_stage_lst, save_anno = dialog.auto_stage(self.midata, self.mianno)
+
+            limit = min(len(self.mianno._sleep_state), len(auto_stage_lst))
+            self.mianno._sleep_state[:limit] = auto_stage_lst[:limit]
+            self._hypo_revision += 1
+
+            if save_anno:
+                self.save_anno()
+            self.is_saved = False
+            self.AnnotationPathLabel.setText("*Annotation path:")
+            self.plot_signals()
+            self.plot_hypo()
+        except ImportError as e:
+            QMessageBox.about(self, "Error", str(e))
+            return
+        except Exception as e:
+            logger.error(f"Auto stage ERROR: {e}")
+            QMessageBox.about(self, "Error", "Auto stage ERROR")
+            return
+
+    # ------------------------------------------------------------------
+    # Saving
+    # ------------------------------------------------------------------
+    def save_anno(self, just_save=False):
+        """Save the annotation to file.
+
+        Parameters
+        ----------
+        just_save : bool
+            Only save without touching the current annotation path.
+        """
+        if self.anno_path == "":
+            anno_path, _ = QFileDialog.getOpenFileName(
+                self, "Select annotation file",
+                f"{self.config['gui']['openpath']}",
+                "txt Files (*.txt *.TXT)")
+            if anno_path == "":
+                return
+            if not just_save:
+                self.anno_path = anno_path
+                self.AnnoPathEdit.setText(self.anno_path)
+
+        save_thread = SaveThread(file=[self.mianno, self.midata],
+                                 file_path=self.anno_path)
+        saved = save_thread.save_anno()
+        if saved and not just_save:
+            self.is_saved = True
+            self.AnnotationPathLabel.setText("Annotation path:")
+        save_thread.quit()
+
+    def save_data(self):
+        """Export (cropped, channel-selected) data to ``.mat``/``.edf``."""
+        dialog = self._ensure_dialog("save_data_dialog", SaveDataDialog)
+        dialog.fill_midata_params(midata=self.midata)
+        dialog.exec()
+        if dialog.closed:
+            return
+
+        selected_channels = [each.row() for each in
+                             dialog.ChannelListView.selectedIndexes()]
+        if selected_channels == []:
+            selected_channels = list(range(self.midata.n_channels))
+        midata_to_save = self.midata.pick_chs(
+            [self.midata.channels[each] for each in selected_channels])
+
+        start_sec = 0
+        end_sec = self.midata.duration
+
+        if dialog.CropDataStartCheckBox.isChecked():
+            start_time = dialog.CropStartTimeEditor.dateTime().toPython()
+            midata_to_save._time = start_time.strftime("%Y%m%d-%H:%M:%S")
+            start_sec = int(datetime.timedelta.total_seconds(start_time - self.ac_time))
+            if start_sec < 0:
+                start_sec = 0
+
+        if dialog.CropDataEndCheckBox.isChecked():
+            end_time = dialog.CropEndTimeEditor.dateTime().toPython()
+            end_sec = int(datetime.timedelta.total_seconds(end_time - self.ac_time))
+            if end_sec > self.midata.duration:
+                end_sec = self.midata.duration
+
+        if end_sec <= start_sec:
+            start_sec = 0
+            end_sec = self.midata.duration
+
+        midata_to_save = midata_to_save.crop([start_sec, end_sec])
+
+        extensions = available_writers()
+        filters = ";;".join(
+            f"{extension[1:].upper()} files (*{extension})"
+            for extension in extensions)
+        data_path, _ = QFileDialog.getSaveFileName(
+            self, "Select a file to save data",
+            f"{self.config['gui']['openpath']}_misleep_saved",
+            filters)
+        if data_path == "":
+            return
+
+        save_thread = SaveThread(file=midata_to_save, file_path=data_path)
+        try:
+            with self._busy_operation():
+                saved = save_thread.save_data()
+        except Exception as exc:
+            logger.exception("Data export failed")
+            QMessageBox.about(self, "Error", f"Data save failed: {exc}")
+            return
+        if saved:
+            QMessageBox.about(self, "Info", f"Data Saved to {data_path}")
+        else:
+            QMessageBox.about(self, "Error", "Data save ERROR")
+        save_thread.quit()
+
+    # ------------------------------------------------------------------
+    # Configuration
+    # ------------------------------------------------------------------
+    def open_settings_dialog(self):
+        """Open the in-application settings dialog."""
+        dialog = SettingsDialog(self)
+        dialog.exec()
+
+    def apply_settings(self):
+        """Apply the current configuration to the running application.
+
+        Called after the settings dialog saves changes, so that state
+        names/colors, labels and spectral defaults take effect
+        immediately without restarting MiSleep.
+        """
+        gui = self.config["gui"]
+
+        # Apply a theme change (chosen in the settings dialog) immediately
+        new_theme = gui.get("theme", fallback="light")
+        new_tone = gui.get("color_tone", fallback="black")
+        if new_theme not in THEMES:
+            new_theme = "light"
+        if new_tone not in COLOR_TONES:
+            new_tone = "black"
+        if new_theme != self._theme_name or new_tone != self._tone_name:
+            self._theme_name = new_theme
+            self._tone_name = new_tone
+            app = QApplication.instance()
+            if app is not None:
+                apply_theme(app, new_theme, new_tone)
+            retheme_figures(new_theme, new_tone)
+            self._set_plot_colors()
+            self._update_theme_action()
+
+        # Reload the parsed dictionaries
+        self.state_map_dict = {int(key): value for key, value
+                               in json.loads(gui["statemap"]).items()}
+        self.state_color_dict = {int(key): value for key, value
+                                 in json.loads(gui["statecolor"]).items()}
+        self.start_end_color_dict = dict(
+            json.loads(gui["startendcolor"].replace("'", '"')).items())
+
+        # Rebuild the state-label buttons (names/colors/extra states)
+        self._sync_state_buttons()
+
+        # Refresh the label picker lists
+        self.label_dialog.marker_label = [
+            each[1:-1] for each in gui["marker"][1:-1].split(", ")]
+        self.label_dialog.start_end_label = [
+            each[1:-1] for each in gui["startend"][1:-1].split(", ")]
+
+        # Refresh spectral defaults used by the state-spectral dialog
+        if self.state_spectral_dialog is not None:
+            self.state_spectral_dialog.GaussianSpinBox.setValue(
+                float(self.config["spec"]["gaussian_sigma"]))
+            self.state_spectral_dialog.WinLengthSpinBox.setValue(
+                float(self.config["spec"]["win_length_sec"]))
+            self.state_spectral_dialog.nfftSpinBox.setValue(
+                int(float(self.config["spec"]["nfft_sec"])))
+
+        # Update the annotation state map if one is loaded
+        if isinstance(self.mianno, MiAnnotation):
+            self.mianno._state_map = self.state_map_dict
+
+        # State names/colors are part of the hypnogram itself. Force a base
+        # rebuild now instead of waiting for the next annotation edit.
+        self._hypo_key = None
+        self._hypo_revision += 1
+        self._hypo_steps = []
+        self._hypo_transient = []
+        # Frequency range changes also invalidate the cached whole-file STFT.
+        self._spec_full_cache = {}
+
+        # Redraw with the new colors / frequency range (skip before data loads)
+        if self.midata is not None and self.mianno is not None:
+            self.redraw_all(second=self.current_sec)
+        else:
+            logger.info("Settings applied; they will take effect after loading data.")
+
+    def pupup_config(self):
+        """Open the user configuration file with the system editor."""
+        import platform
+        import subprocess
+
+        path = str(user_config_path())
+        try:
+            system = platform.system()
+            if system == "Windows":
+                os.startfile(path)
+            elif system == "Darwin":
+                subprocess.run(["open", path])
+            elif system == "Linux":
+                subprocess.run(["xdg-open", path])
+        except Exception as e:
+            logger.error(f"Open config.ini ERROR: {e}")
+            QMessageBox.about(self, "Error", f"Open config.ini ERROR: {e}")
+
+    def auto_save(self):
+        """Auto-save the annotation every 5 minutes when modified."""
+        if not self.is_saved:
+            self.save_anno()
+        self.save_timer.start(5 * 60 * 1000)
+
+    def save_config(self, config_dict):
+        """Persist GUI configuration changes to the user config file."""
+        for key, value in config_dict.items():
+            self.config.set("gui", key, value)
+        save_config(self.config)
+
+    # ------------------------------------------------------------------
+    # Event handlers
+    # ------------------------------------------------------------------
+    def keyPressEvent(self, event):
+        """Number keys label the selected area with that state.
+
+        Keys 1-9 map to states 1-9; key 0 maps to state 10 (when defined),
+        supporting up to ten states.
+        """
+        if Qt.Key.Key_0 <= event.key() <= Qt.Key.Key_9:
+            num = int(event.text())
+            state = 10 if num == 0 else num
+            if state in self.state_map_dict.keys():
+                self.sleep_state_label(state_code=state)
+        else:
+            QWidget.keyPressEvent(self, event)
+
+    def closeEvent(self, event):
+        """Ask for confirmation when there are unsaved labels."""
+        if not self.is_saved:
+            box = QMessageBox.question(
+                self, "Warning",
+                "Your labels haven't been saved, discard?\n"
+                "Yes: Save and quit\nNo: Discard\nCancel: Nothing",
+                QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No
+                | QMessageBox.StandardButton.Cancel,
+                QMessageBox.StandardButton.Yes)
+
+            if box == QMessageBox.StandardButton.Yes:
+                self.save_anno()
+                event.accept()
+            elif box == QMessageBox.StandardButton.No:
+                event.accept()
+            else:
+                event.ignore()
+
+        if event.isAccepted():
+            self.save_timer.stop()
+            if self.spec_window is not None:
+                self.spec_window.close()
+            plt.close(self.signal_figure)
+            plt.close(self.hypo_figure)
+
+
+# Backward-compatible alias
+main_window = MainWindow