matchpatch 0.4.0__py3-none-any.whl

matchpatch/gui/app.py

@@ -0,0 +1,193 @@
+"""Application entry point for the MatchPatch PySide6 GUI."""
+
+from __future__ import annotations
+
+import os
+import signal
+import sys
+from pathlib import Path
+
+from PySide6.QtCore import QMessageLogContext, Qt, QTimer, QtMsgType, qInstallMessageHandler
+from PySide6.QtGui import QColor, QFont, QGuiApplication, QIcon, QImage, QPainter
+from PySide6.QtWidgets import QApplication
+
+from matchpatch.gui.main_window import MainWindow
+
+IGNORED_QT_MESSAGES = {"This plugin supports grabbing the mouse only for popup windows"}
+SOURCE_ROOT = Path(__file__).resolve().parents[3]
+DESKTOP_FILE_ID = "matchpatch-gui"
+DESKTOP_ICON_SIZE = 512
+DEFAULT_XDG_DATA_DIRS = "/usr/local/share:/usr/share"
+GUI_STYLE = "Fusion"
+GUI_FONT_FAMILY = "DejaVu Sans"
+GUI_FONT_POINT_SIZE = 10
+GUI_SMOKE_ENV = "MATCHPATCH_GUI_SMOKE"
+
+
+def resource_path(*parts: str) -> Path:
+    """Resolve bundled resources in frozen and source-tree execution."""
+    relative_path = Path(*parts)
+    candidates: list[Path] = []
+    meipass = getattr(sys, "_MEIPASS", None)
+    if getattr(sys, "frozen", False):
+        if meipass:
+            candidates.append(Path(meipass) / relative_path)
+        candidates.append(Path(sys.executable).resolve().parent / relative_path)
+    candidates.append(SOURCE_ROOT / relative_path)
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return candidates[0]
+
+
+def assets_dir() -> Path:
+    return resource_path("docs", "assets")
+
+
+def qt_message_handler(
+    message_type: QtMsgType,
+    context: QMessageLogContext,
+    message: str,
+) -> None:
+    """Suppress known harmless platform noise while preserving other Qt messages."""
+    del message_type, context
+    if message not in IGNORED_QT_MESSAGES:
+        print(message, file=sys.stderr)
+
+
+def configure_wslg_runtime() -> None:
+    """Point Qt at WSLg when systemd provides a runtime dir without its socket."""
+    wayland_display = os.getenv("WAYLAND_DISPLAY")
+    if not wayland_display:
+        return
+
+    runtime_dir = Path(os.getenv("XDG_RUNTIME_DIR", ""))
+    if runtime_dir.joinpath(wayland_display).exists():
+        return
+
+    wslg_runtime = Path("/mnt/wslg/runtime-dir")
+    if wslg_runtime.joinpath(wayland_display).exists():
+        os.environ["XDG_RUNTIME_DIR"] = str(wslg_runtime)
+        os.environ.setdefault("QT_QPA_PLATFORM", "wayland")
+
+
+def configure_high_dpi_scaling() -> None:
+    """Keep Qt's per-screen scale factors stable across platforms."""
+    QGuiApplication.setHighDpiScaleFactorRoundingPolicy(
+        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough
+    )
+
+
+def configure_gui_appearance(app: QApplication) -> None:
+    """Apply the WSLg visual baseline consistently on every Qt platform."""
+    app.setStyle(GUI_STYLE)
+    app.setFont(QFont(GUI_FONT_FAMILY, GUI_FONT_POINT_SIZE))
+    app.setPalette(app.style().standardPalette())
+
+
+def _write_square_desktop_icon(source: Path, target: Path) -> None:
+    image = QImage(str(source))
+    if image.isNull():
+        return
+
+    icon = QImage(DESKTOP_ICON_SIZE, DESKTOP_ICON_SIZE, QImage.Format.Format_ARGB32)
+    icon.fill(QColor(0, 0, 0, 0))
+    scaled = image.scaled(
+        DESKTOP_ICON_SIZE,
+        DESKTOP_ICON_SIZE,
+        Qt.AspectRatioMode.KeepAspectRatio,
+        Qt.TransformationMode.SmoothTransformation,
+    )
+    x = (DESKTOP_ICON_SIZE - scaled.width()) // 2
+    y = (DESKTOP_ICON_SIZE - scaled.height()) // 2
+    painter = QPainter(icon)
+    painter.drawImage(x, y, scaled)
+    painter.end()
+    icon.save(str(target))
+
+
+def _desktop_entry_data_dirs() -> list[Path]:
+    data_home = Path(os.getenv("XDG_DATA_HOME", str(Path.home() / ".local" / "share")))
+    data_dirs = [
+        Path(path)
+        for path in os.getenv("XDG_DATA_DIRS", DEFAULT_XDG_DATA_DIRS).split(os.pathsep)
+        if path
+    ]
+    return [*data_dirs, data_home]
+
+
+def _desktop_entry(icon: Path) -> str:
+    return (
+        "[Desktop Entry]\n"
+        "Type=Application\n"
+        "Name=MatchPatch\n"
+        "Comment=Normalize audio processor presets\n"
+        "Exec=matchpatch-gui\n"
+        f"Icon={icon}\n"
+        "Terminal=false\n"
+        "Categories=AudioVideo;Audio;\n"
+        f"StartupWMClass={DESKTOP_FILE_ID}\n"
+    )
+
+
+def register_desktop_entry() -> None:
+    """Give Wayland/WSLg an application ID with a project icon."""
+    for data_dir in _desktop_entry_data_dirs():
+        applications = data_dir / "applications"
+        icons = data_dir / "icons" / "hicolor" / "512x512" / "apps"
+        desktop_file = applications / f"{DESKTOP_FILE_ID}.desktop"
+        installed_icon = icons / f"{DESKTOP_FILE_ID}.png"
+        entry = _desktop_entry(installed_icon)
+        try:
+            applications.mkdir(parents=True, exist_ok=True)
+            icons.mkdir(parents=True, exist_ok=True)
+            _write_square_desktop_icon(assets_dir() / "matchmatch-icon-512.png", installed_icon)
+            if not desktop_file.exists() or desktop_file.read_text(encoding="utf-8") != entry:
+                desktop_file.write_text(entry, encoding="utf-8")
+        except OSError:
+            continue
+
+
+def install_terminal_interrupt_handler(app: QApplication, window: MainWindow) -> QTimer:
+    """Route terminal cancellation through the window's normal close handling."""
+
+    def close_window(_signum: int, _frame: object) -> None:
+        QTimer.singleShot(0, window.close)
+
+    signal.signal(signal.SIGINT, close_window)
+    timer = QTimer(app)
+    timer.timeout.connect(lambda: None)
+    timer.start(100)
+    return timer
+
+
+def gui_smoke_enabled() -> bool:
+    return os.getenv(GUI_SMOKE_ENV, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def main(argv: list[str] | None = None) -> None:
+    configure_wslg_runtime()
+    configure_high_dpi_scaling()
+    register_desktop_entry()
+    qInstallMessageHandler(qt_message_handler)
+    app = QApplication([sys.argv[0], *(argv or [])])
+    configure_gui_appearance(app)
+    app.setApplicationName(DESKTOP_FILE_ID)
+    app.setApplicationDisplayName("MatchPatch")
+    app.setDesktopFileName(DESKTOP_FILE_ID)
+    icon = assets_dir() / "matchmatch-icon.png"
+    app.setWindowIcon(QIcon(str(icon)))
+    window = MainWindow()
+    if gui_smoke_enabled():
+        window.show()
+        app.processEvents()
+        window.close()
+        raise SystemExit(0)
+    window.showMaximized()
+    _interrupt_timer = install_terminal_interrupt_handler(app, window)
+    raise SystemExit(app.exec())
+
+
+if __name__ == "__main__":  # pragma: no cover - module entry point
+    main()

matchpatch/gui/device_panels.py

@@ -0,0 +1,142 @@
+"""Device-specific settings panels for the MatchPatch GUI."""
+
+from __future__ import annotations
+
+import argparse
+
+from PySide6.QtWidgets import (
+    QFormLayout,
+    QGroupBox,
+    QLabel,
+    QLineEdit,
+    QSpinBox,
+    QVBoxLayout,
+    QWidget,
+)
+
+
+class HelixSettingsPanel(QWidget):
+    def __init__(self, backend_selector: QWidget | None = None) -> None:
+        super().__init__()
+        layout = QVBoxLayout(self)
+        self.audio_group = QGroupBox("Audio routing")
+        self.steering_group = QGroupBox("MIDI steering")
+        layout.addWidget(self.audio_group)
+        layout.addWidget(self.steering_group)
+        if backend_selector is not None:
+            backend = QFormLayout()
+            backend.addRow(
+                _label(
+                    "Backend", "Select loopback for testing or hardware for a connected device."
+                ),
+                backend_selector,
+            )
+            layout.addLayout(backend)
+        layout.addStretch()
+
+        audio = QFormLayout(self.audio_group)
+        self.audio_device = QLineEdit()
+        self.sample_rate = QSpinBox()
+        self.sample_rate.setRange(1, 384000)
+        self.input_mapping = QLineEdit()
+        self.output_mapping = QLineEdit()
+        self.blocksize = QSpinBox()
+        self.blocksize.setRange(0, 65536)
+        audio.addRow(
+            _label("Audio device", "Windows audio-interface name used for Helix I/O."),
+            self.audio_device,
+        )
+        audio.addRow(
+            _label(
+                "Sample rate",
+                "Audio sample rate used while replaying and recording the reference DI.",
+            ),
+            self.sample_rate,
+        )
+        audio.addRow(
+            _label(
+                "Recording channels", "Input channels carrying the Helix-processed stereo signal."
+            ),
+            self.input_mapping,
+        )
+        audio.addRow(
+            _label("Playback channels", "Output channels sending the reference DI to the Helix."),
+            self.output_mapping,
+        )
+        audio.addRow(
+            _label("Block size", "Audio buffer size. Use 0 to let the audio backend decide."),
+            self.blocksize,
+        )
+
+        steering = QFormLayout(self.steering_group)
+        self.steering_output = QLineEdit()
+        self.steering_channel = QSpinBox()
+        self.steering_channel.setRange(0, 15)
+        self.preset_wait = QLineEdit()
+        self.snapshot_wait = QLineEdit()
+        self.measurement_wait = QLineEdit()
+        steering.addRow(
+            _label("MIDI output", "MIDI port substring used to find the connected Helix."),
+            self.steering_output,
+        )
+        steering.addRow(
+            _label("MIDI channel", "Zero-based MIDI channel used for preset and snapshot changes."),
+            self.steering_channel,
+        )
+        steering.addRow(
+            _label("Preset wait (s)", "Pause after switching presets before continuing."),
+            self.preset_wait,
+        )
+        steering.addRow(
+            _label("Snapshot wait (s)", "Pause after switching snapshots before continuing."),
+            self.snapshot_wait,
+        )
+        steering.addRow(
+            _label(
+                "Measurement wait (s)", "Pause before capturing loudness after a snapshot change."
+            ),
+            self.measurement_wait,
+        )
+
+    def populate(self, args: argparse.Namespace) -> None:
+        self.audio_device.setText(_text(args.audio_device or "Helix"))
+        self.sample_rate.setValue(args.sample_rate or 48000)
+        self.input_mapping.setText(args.input_mapping or "1,2")
+        self.output_mapping.setText(args.output_mapping or "3,4")
+        self.blocksize.setValue(args.blocksize or 0)
+        self.steering_output.setText(_text(args.steering_output or "Helix"))
+        self.steering_channel.setValue(args.steering_channel or 0)
+        self.preset_wait.setText(_text(args.preset_wait if args.preset_wait is not None else 0.5))
+        self.snapshot_wait.setText(
+            _text(args.snapshot_wait if args.snapshot_wait is not None else 0.2)
+        )
+        self.measurement_wait.setText(
+            _text(args.measurement_wait if args.measurement_wait is not None else 0.1)
+        )
+
+    def append_arguments(self, argv: list[str]) -> None:
+        _append(argv, "--audio-device", self.audio_device.text())
+        _append(argv, "--sample-rate", self.sample_rate.value())
+        _append(argv, "--input-mapping", self.input_mapping.text())
+        _append(argv, "--output-mapping", self.output_mapping.text())
+        _append(argv, "--blocksize", self.blocksize.value())
+        _append(argv, "--steering-output", self.steering_output.text())
+        _append(argv, "--steering-channel", self.steering_channel.value())
+        _append(argv, "--preset-wait", self.preset_wait.text())
+        _append(argv, "--snapshot-wait", self.snapshot_wait.text())
+        _append(argv, "--measurement-wait", self.measurement_wait.text())
+
+
+def _append(argv: list[str], name: str, value: object) -> None:
+    if str(value).strip():
+        argv.extend([name, str(value)])
+
+
+def _text(value: object | None) -> str:
+    return "" if value is None else str(value)
+
+
+def _label(text: str, tooltip: str) -> QLabel:
+    label = QLabel(text)
+    label.setToolTip(tooltip)
+    return label

matchpatch/gui/dialogs.py

@@ -0,0 +1,150 @@
+"""Help and About dialogs for the MatchPatch GUI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QColor, QFont, QIcon, QPainter, QPixmap
+from PySide6.QtWidgets import (
+    QApplication,
+    QDialog,
+    QDialogButtonBox,
+    QLabel,
+    QStyle,
+    QTextBrowser,
+    QVBoxLayout,
+    QWidget,
+)
+
+from matchpatch import __version__
+from matchpatch.gui.help import HelpId, resolve_help_url
+
+PROJECT_URL = "https://github.com/noseglasses/MatchPatch"
+ASSETS_DIR = Path(__file__).resolve().parents[3] / "docs" / "assets"
+
+
+def _about_icon_blue(size: int) -> QColor:
+    pixmap = (
+        QApplication.style()
+        .standardIcon(QStyle.StandardPixmap.SP_MessageBoxInformation)
+        .pixmap(size, size)
+    )
+    image = pixmap.toImage()
+    red_total = 0
+    green_total = 0
+    blue_total = 0
+    count = 0
+    for y in range(image.height()):
+        for x in range(image.width()):
+            color = image.pixelColor(x, y)
+            if color.alpha() <= 0:
+                continue
+            if 180 <= color.hue() <= 250 and color.saturation() >= 60 and color.value() >= 80:
+                red_total += color.red()
+                green_total += color.green()
+                blue_total += color.blue()
+                count += 1
+    if count == 0:
+        return QColor("#308cc6")
+    return QColor(red_total // count, green_total // count, blue_total // count)
+
+
+def _question_mark_icon() -> QIcon:
+    pixmap = QPixmap(64, 64)
+    pixmap.fill(Qt.GlobalColor.transparent)
+
+    painter = QPainter(pixmap)
+    painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+    painter.setPen(Qt.PenStyle.NoPen)
+    painter.setBrush(_about_icon_blue(64))
+    painter.drawEllipse(4, 4, 56, 56)
+    painter.setPen(QColor("#ffffff"))
+    font = QFont()
+    font.setBold(True)
+    font.setPointSize(40)
+    painter.setFont(font)
+    painter.drawText(pixmap.rect(), Qt.AlignmentFlag.AlignCenter, "?")
+    painter.end()
+    return QIcon(pixmap)
+
+
+class AboutDialog(QDialog):
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self.setWindowTitle("About MatchPatch")
+        self.setProperty("help_id", HelpId.DOCS_INDEX)
+        self.setWindowIcon(
+            QApplication.style().standardIcon(QStyle.StandardPixmap.SP_MessageBoxInformation)
+        )
+        self.setMinimumWidth(560)
+        layout = QVBoxLayout(self)
+        logo = QLabel()
+        pixmap = QPixmap(str(ASSETS_DIR / "matchmatch-logo.png"))
+        logo.setPixmap(
+            pixmap.scaled(
+                520,
+                320,
+                Qt.AspectRatioMode.KeepAspectRatio,
+                Qt.TransformationMode.SmoothTransformation,
+            )
+        )
+        logo.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        layout.addWidget(logo)
+        details = QLabel(
+            "<h2>MatchPatch</h2>"
+            f"<p>Version {__version__}</p>"
+            "<p>Automatic loudness alignment for audio-processor presets and snapshots.</p>"
+            f'<p><a href="{resolve_help_url(HelpId.DOCS_INDEX).toString()}">'
+            "Documentation</a></p>"
+            f'<p><a href="{PROJECT_URL}">{PROJECT_URL}</a></p>'
+            "<p>Copyright © 2026 MatchPatch contributors.</p>"
+            "<p>Open source software released under the MIT License.</p>"
+            "<p>Keep backups of original processor files. Generated measurement files are "
+            "intended for measurement workflows only.</p>"
+        )
+        details.setOpenExternalLinks(True)
+        details.setWordWrap(True)
+        layout.addWidget(details)
+        buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
+        buttons.rejected.connect(self.reject)
+        layout.addWidget(buttons)
+
+
+class HelpDialog(QDialog):
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self.setWindowTitle("MatchPatch Help")
+        self.setWindowIcon(_question_mark_icon())
+        self.resize(680, 520)
+        layout = QVBoxLayout(self)
+        help_text = QTextBrowser()
+        help_text.setOpenExternalLinks(True)
+        help_text.setHtml(
+            "<h2>Guided normalization</h2>"
+            "<ol>"
+            "<li>Open a Helix <code>.hls</code> setlist or <code>.hlx</code> preset from "
+            "the toolbar.</li>"
+            "<li>The default <b>hardware</b> backend steers and measures the connected Helix. "
+            "Use <b>loopback</b> only for testing without hardware.</li>"
+            "<li>Use the <b>Presets</b> panel to change preset selection. Expand "
+            "<b>Advanced</b> to change device settings, miscellaneous policy values, "
+            "or inspect the log.</li>"
+            "<li>Start normalization and follow the import dialog for the generated measurement "
+            "file.</li>"
+            "<li>Use toolbar save or save-as to write the adjusted setlist or preset.</li>"
+            "</ol>"
+            "<h3>Progress</h3>"
+            "<p>A pulsing green dot in the window footer means MatchPatch is working. "
+            "The dot is grey while MatchPatch is idle and red after a measurement was "
+            "cancelled. While presets are measured, a determinate progress pane shows "
+            "the current preset and snapshot.</p>"
+            "<h3>Temporary files</h3>"
+            "<p>Enable <b>Keep temporary files</b> to retain the measurement CSV. "
+            "Its exact path appears below the processing controls.</p>"
+            f'<p>More documentation: <a href="{PROJECT_URL}">{PROJECT_URL}</a></p>'
+        )
+        layout.addWidget(help_text)
+        buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
+        buttons.rejected.connect(self.reject)
+        layout.addWidget(buttons)

matchpatch/gui/help.py

@@ -0,0 +1,213 @@
+"""Offline help topic IDs and URL resolution for the MatchPatch GUI."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from PySide6.QtCore import QUrl
+from PySide6.QtGui import QDesktopServices
+
+GITHUB_DOCS_URL = "https://github.com/noseglasses/MatchPatch/tree/main/docs"
+
+
+class HelpId:
+    DOCS_INDEX = "docs_index"
+    QUICK_START = "quick_start"
+    OPEN_FILES = "open_files"
+    SAVE_IMPORT = "save_import"
+    MEASUREMENT_FILE = "measurement_file"
+    NORMALIZE_SETLIST = "normalize_setlist"
+    NORMALIZE_SINGLE_PRESET = "normalize_single_preset"
+    PROGRESS_CANCEL = "progress_cancel"
+    RECORDED_OUTPUT = "recorded_output"
+    ADVANCED_SETTINGS = "advanced_settings"
+    SELECT_PRESETS = "select_presets"
+    SELECT_CHANGED = "select_changed"
+    MANUAL_EDITING = "manual_editing"
+    MANUAL_CSV = "manual_csv"
+    SNAPSHOTS_SOLOS_IGNORED = "snapshots_solos_ignored"
+    READING_RESULTS = "reading_results"
+    BACKENDS = "backends"
+    ROUTING_LEVELS = "routing_levels"
+    HARDWARE_MEASUREMENT = "hardware_measurement"
+    FILES_TAB = "files_tab"
+    REFERENCE_DI = "reference_di"
+    CUSTOM_ADJUSTMENTS = "custom_adjustments"
+    TIMING = "timing"
+    OPTIMIZE_TIMING = "optimize_timing"
+    LUFS_LOUDNESS = "lufs_loudness"
+    SNAPSHOT_COUNT = "snapshot_count"
+    METADATA = "metadata"
+    TROUBLESHOOTING = "troubleshooting"
+    HARDWARE_TROUBLESHOOTING = "hardware_troubleshooting"
+    OPTIMIZE_TIMING_RESULTS = "optimize_timing_results"
+
+
+@dataclass(frozen=True)
+class HelpTopic:
+    page: str
+    anchor: str | None = None
+
+
+HELP_TOPICS: dict[str, HelpTopic] = {
+    HelpId.DOCS_INDEX: HelpTopic("index.html"),
+    HelpId.QUICK_START: HelpTopic("quick-start.html"),
+    HelpId.OPEN_FILES: HelpTopic("musician-guide.html", "help-opening-files"),
+    HelpId.SAVE_IMPORT: HelpTopic("workflows/save-and-import.html"),
+    HelpId.MEASUREMENT_FILE: HelpTopic(
+        "concepts/measurement-and-adjusted-files.html",
+        "help-measurement-file",
+    ),
+    HelpId.NORMALIZE_SETLIST: HelpTopic("workflows/normalize-setlist.html"),
+    HelpId.NORMALIZE_SINGLE_PRESET: HelpTopic("workflows/normalize-single-preset.html"),
+    HelpId.PROGRESS_CANCEL: HelpTopic("concepts/reading-results.html", "help-progress-and-cancel"),
+    HelpId.RECORDED_OUTPUT: HelpTopic(
+        "workflows/hardware-measurement.html",
+        "help-recorded-output-playback",
+    ),
+    HelpId.ADVANCED_SETTINGS: HelpTopic("musician-guide.html", "help-advanced-settings"),
+    HelpId.SELECT_PRESETS: HelpTopic("workflows/normalize-setlist.html", "help-select-presets"),
+    HelpId.SELECT_CHANGED: HelpTopic("workflows/select-changed-presets.html"),
+    HelpId.MANUAL_EDITING: HelpTopic(
+        "workflows/manual-editing-and-csv.html",
+        "help-manual-editing",
+    ),
+    HelpId.MANUAL_CSV: HelpTopic("workflows/manual-editing-and-csv.html", "help-csv"),
+    HelpId.SNAPSHOTS_SOLOS_IGNORED: HelpTopic("concepts/snapshots-solos-and-ignored.html"),
+    HelpId.READING_RESULTS: HelpTopic("concepts/reading-results.html"),
+    HelpId.BACKENDS: HelpTopic("concepts/backends.html"),
+    HelpId.ROUTING_LEVELS: HelpTopic("concepts/routing-and-levels.html", "help-audio-routing"),
+    HelpId.HARDWARE_MEASUREMENT: HelpTopic("workflows/hardware-measurement.html"),
+    HelpId.FILES_TAB: HelpTopic("concepts/measurement-and-adjusted-files.html"),
+    HelpId.REFERENCE_DI: HelpTopic("concepts/reference-di.html", "help-reference-di"),
+    HelpId.CUSTOM_ADJUSTMENTS: HelpTopic("workflows/custom-adjustments.html"),
+    HelpId.TIMING: HelpTopic("concepts/timing.html"),
+    HelpId.OPTIMIZE_TIMING: HelpTopic("workflows/optimize-timing.html"),
+    HelpId.LUFS_LOUDNESS: HelpTopic("concepts/lufs-and-loudness.html"),
+    HelpId.SNAPSHOT_COUNT: HelpTopic(
+        "concepts/snapshots-solos-and-ignored.html",
+        "help-snapshot-count",
+    ),
+    HelpId.METADATA: HelpTopic("musician-guide.html", "help-metadata"),
+    HelpId.TROUBLESHOOTING: HelpTopic("troubleshooting.html"),
+    HelpId.HARDWARE_TROUBLESHOOTING: HelpTopic("troubleshooting.html", "help-hardware-not-found"),
+    HelpId.OPTIMIZE_TIMING_RESULTS: HelpTopic(
+        "workflows/optimize-timing.html",
+        "help-apply-optimized-timing",
+    ),
+}
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[3]
+
+
+def _docs_root_if_available(path: Path) -> Path | None:
+    if (path / "index.html").is_file():
+        return path
+    return None
+
+
+def local_docs_root() -> Path | None:
+    if getattr(sys, "frozen", False):
+        executable = getattr(sys, "executable", "")
+        if executable:
+            if packaged_docs := _docs_root_if_available(
+                Path(executable).resolve().parent / "docs_html"
+            ):
+                return packaged_docs
+
+    if checkout_docs := _docs_root_if_available(repo_root() / "docs_html"):
+        return checkout_docs
+
+    return None
+
+
+def resolve_help_url(help_id: str, *, docs_root: Path | None = None) -> QUrl:
+    topic = HELP_TOPICS.get(help_id, HELP_TOPICS[HelpId.DOCS_INDEX])
+    if docs_root is None:
+        docs_root = local_docs_root()
+
+    if docs_root is not None:
+        target = docs_root / topic.page
+        if target.is_file():
+            url = QUrl.fromLocalFile(str(target))
+            if topic.anchor:
+                url.setFragment(topic.anchor)
+            return url
+
+    source_page = topic.page.removesuffix(".html") + ".md"
+    url = QUrl(f"{GITHUB_DOCS_URL}/{source_page}")
+    if topic.anchor:
+        url.setFragment(topic.anchor)
+    return url
+
+
+def _running_under_wsl() -> bool:
+    if sys.platform != "linux":
+        return False
+    try:
+        version = Path("/proc/version").read_text(encoding="utf-8").casefold()
+    except OSError:
+        return False
+    return "microsoft" in version or "wsl" in version
+
+
+def _wslpath_to_windows(path: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["wslpath", "-w", str(path)],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def _url_for_wsl_launcher(url: QUrl) -> str:
+    if not url.isLocalFile():
+        return url.toString()
+
+    launcher_url = _wslpath_to_windows(Path(url.toLocalFile())) or url.toLocalFile()
+    if fragment := url.fragment():
+        launcher_url = f"{launcher_url}#{fragment}"
+    return launcher_url
+
+
+def _open_url_with_wsl_launcher(url: QUrl) -> bool:
+    launcher_url = _url_for_wsl_launcher(url)
+    commands = []
+    if wslview := shutil.which("wslview"):
+        commands.append([wslview, launcher_url])
+    if shutil.which("cmd.exe"):
+        commands.append(["cmd.exe", "/d", "/c", "start", "", launcher_url])
+
+    for command in commands:
+        try:
+            result = subprocess.run(
+                command,
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except OSError:
+            continue
+        if result.returncode == 0:
+            return True
+    return False
+
+
+def open_help(help_id: str = HelpId.DOCS_INDEX) -> bool:
+    url = resolve_help_url(help_id)
+    if _running_under_wsl() and _open_url_with_wsl_launcher(url):
+        return True
+    return QDesktopServices.openUrl(url)