feat(miniapp): add CDP debug port support

- Enables Chrome DevTools Protocol debugging per-app via a configurable
  port, so developers can attach browser devtools without modifying the
  host process or using a global flag.
- Port is validated before launch with a bind-test to fail fast instead
  of silently ignoring a conflict at runtime.
- CDP URL is discovered via polling after WebView2 init and surfaced in
  both the toolbar button and the context menu, avoiding any need to
  hunt for the URL manually.
- Environment variable injection is scoped tightly around the
  CreateCoreWebView2EnvironmentWithOptions call and restored immediately
  so concurrent launches on different ports cannot race.

Author: nullmastermind

src/MiniAppDefinition.h

@@ -20,6 +20,7 @@ struct MiniAppDefinition
     QString icon;             // Reserved for future custom icon path
     QString healthCheckUrl;   // Health poll URL (defaults to url if empty)
     int healthTimeoutMs = 30000; // Timeout in ms (range 5000-300000)
+    int debugPort = 0;           // CDP debug port (0 = disabled, 1-65535 = enabled)
     bool autoKillOnClose = true; // Kill process on tab close
 
     bool isValid() const { return !name.isEmpty() && !url.isEmpty(); }

src/MiniAppInstance.cpp

@@ -14,6 +14,8 @@
 #include <QNetworkAccessManager>
 #include <QNetworkReply>
 #include <QNetworkRequest>
+#include <QTcpSocket>
+#include <QHostAddress>
 #include <QUrl>
 
 MiniAppInstance::MiniAppInstance(const MiniAppDefinition &def, QObject *parent)
@@ -55,6 +57,11 @@ QString MiniAppInstance::debugInfo() const
         info += QStringLiteral("\n");
         info += m_webView->debugInfo();
     }
+    if (!m_cdpHttpUrl.isEmpty()) {
+        info += QStringLiteral("\n--- CDP ---\n");
+        info += QStringLiteral("CDP HTTP URL: %1\n").arg(m_cdpHttpUrl);
+        info += QStringLiteral("CDP WebSocket URL: %1\n").arg(m_cdpWsUrl);
+    }
     return info;
 }
 
@@ -65,6 +72,17 @@ void MiniAppInstance::start()
 
     setState(Idle);
 
+    // Pre-launch bind-test for CDP debug port
+    if (m_def.debugPort > 0) {
+        QTcpSocket sock;
+        if (!sock.bind(QHostAddress::LocalHost, static_cast<quint16>(m_def.debugPort))) {
+            m_lastError = tr("Debug port %1 is in use").arg(m_def.debugPort);
+            setState(Failed);
+            return;
+        }
+        sock.close();
+    }
+
     if (!m_def.command.isEmpty()) {
         spawnProcess();
     } else {
@@ -87,6 +105,8 @@ void MiniAppInstance::retry()
         m_webView->deleteLater();
         m_webView = nullptr;
     }
+    m_cdpHttpUrl.clear();
+    m_cdpWsUrl.clear();
     start();
 }
 
@@ -112,13 +132,24 @@ void MiniAppInstance::destroy()
         m_nam->deleteLater();
         m_nam = nullptr;
     }
+    m_cdpHttpUrl.clear();
+    m_cdpWsUrl.clear();
     emit finished();
 }
 
 void MiniAppInstance::setState(State s)
 {
     if (m_state == s) return;
     m_state = s;
+
+    // Clear CDP URLs on terminal/idle states per spec
+    if (s == Failed || s == Crashed || s == Idle) {
+        m_cdpHttpUrl.clear();
+        m_cdpWsUrl.clear();
+        if (m_webView)
+            m_webView->hideCdpUrl();
+    }
+
     emit stateChanged(s);
     emit titleChanged(buildTitle());
 }
@@ -261,7 +292,7 @@ void MiniAppInstance::onHealthPoll()
 
 void MiniAppInstance::createWebView()
 {
-    m_webView = WebViewWidget::create(m_def.id, QUrl(m_def.url), nullptr);
+    m_webView = WebViewWidget::create(m_def.id, QUrl(m_def.url), m_def.debugPort, nullptr);
     if (!m_webView) {
         // Platform doesn't support embedded webview (Linux)
         setState(Running);
@@ -272,6 +303,12 @@ void MiniAppInstance::createWebView()
             this, &MiniAppInstance::onWebViewNavigationCompleted);
     connect(m_webView, &WebViewWidget::processFailed,
             this, &MiniAppInstance::onWebViewProcessFailed);
+    connect(m_webView, &WebViewWidget::cdpReady,
+            this, [this](const QString &httpUrl, const QString &wsUrl) {
+                m_cdpHttpUrl = httpUrl;
+                m_cdpWsUrl = wsUrl;
+                emit cdpUrlChanged(httpUrl);
+            });
 
     setState(Initializing);
 }

src/MiniAppInstance.h

@@ -20,6 +20,7 @@
 
 class QNetworkAccessManager;
 class QNetworkReply;
+class QTcpSocket;
 class WebViewWidget;
 
 class MiniAppInstance : public QObject
@@ -49,6 +50,9 @@ class MiniAppInstance : public QObject
     const MiniAppDefinition &definition() const { return m_def; }
     QString debugInfo() const;
 
+    QString cdpHttpUrl() const { return m_cdpHttpUrl; }
+    QString cdpWsUrl() const { return m_cdpWsUrl; }
+
     WebViewWidget *webViewWidget() const { return m_webView; }
     void setDockWidget(ads::CDockWidget *dw) { m_dockWidget = dw; }
     ads::CDockWidget *dockWidget() const { return m_dockWidget; }
@@ -60,6 +64,7 @@ class MiniAppInstance : public QObject
 signals:
     void stateChanged(MiniAppInstance::State newState);
     void titleChanged(const QString &title);
+    void cdpUrlChanged(const QString &httpUrl);
     void finished();
 
 private slots:
@@ -86,5 +91,7 @@ private slots:
     WebViewWidget *m_webView = nullptr;
     QPointer<ads::CDockWidget> m_dockWidget;
     QString m_lastError;
+    QString m_cdpHttpUrl;
+    QString m_cdpWsUrl;
 };
 

src/MiniAppManager.cpp

@@ -12,6 +12,8 @@
 #include "NotepadNextApplication.h"
 #include "WebViewWidget.h"
 
+#include <QApplication>
+#include <QClipboard>
 #include <QDesktopServices>
 #include <QDialog>
 #include <QFont>
@@ -140,6 +142,12 @@ void MiniAppManager::launchApp(const MiniAppDefinition &def)
             layout->addWidget(text);
             dlg.exec();
         });
+        if (instance->definition().debugPort > 0) {
+            QAction *cdpAction = menu.addAction(tr("Copy CDP URL"), this, [instance]() {
+                QApplication::clipboard()->setText(instance->cdpHttpUrl());
+            });
+            cdpAction->setEnabled(!instance->cdpHttpUrl().isEmpty());
+        }
         menu.addSeparator();
         menu.addAction(tr("Retry"), instance, &MiniAppInstance::retry);
         menu.addAction(tr("Close"), dw, &ads::CDockWidget::closeDockWidget);

src/MiniAppRegistry.cpp

@@ -61,6 +61,7 @@ QList<MiniAppDefinition> MiniAppRegistry::workspaceApps(const QString &workspace
         def.icon = obj.value(QStringLiteral("icon")).toString();
         def.healthCheckUrl = obj.value(QStringLiteral("healthCheckUrl")).toString();
         def.healthTimeoutMs = obj.value(QStringLiteral("healthTimeoutMs")).toInt(30000);
+        def.debugPort = obj.value(QStringLiteral("debugPort")).toInt(0);
         def.autoKillOnClose = obj.value(QStringLiteral("autoKillOnClose")).toBool(true);
         if (!def.name.isEmpty())
             result.append(def);
@@ -100,6 +101,7 @@ void MiniAppRegistry::setWorkspaceApps(const QString &workspacePath, const QList
         if (!def.icon.isEmpty()) obj.insert(QStringLiteral("icon"), def.icon);
         if (!def.healthCheckUrl.isEmpty()) obj.insert(QStringLiteral("healthCheckUrl"), def.healthCheckUrl);
         if (def.healthTimeoutMs != 30000) obj.insert(QStringLiteral("healthTimeoutMs"), def.healthTimeoutMs);
+        if (def.debugPort > 0) obj.insert(QStringLiteral("debugPort"), def.debugPort);
         if (!def.autoKillOnClose) obj.insert(QStringLiteral("autoKillOnClose"), false);
         arr.append(obj);
     }
@@ -157,6 +159,7 @@ QList<MiniAppDefinition> MiniAppRegistry::parseJson(const QString &json)
         def.icon = obj.value(QStringLiteral("icon")).toString();
         def.healthCheckUrl = obj.value(QStringLiteral("healthCheckUrl")).toString();
         def.healthTimeoutMs = obj.value(QStringLiteral("healthTimeoutMs")).toInt(30000);
+        def.debugPort = obj.value(QStringLiteral("debugPort")).toInt(0);
         def.autoKillOnClose = obj.value(QStringLiteral("autoKillOnClose")).toBool(true);
         if (!def.name.isEmpty())
             result.append(def);
@@ -179,6 +182,7 @@ QString MiniAppRegistry::toJson(const QList<MiniAppDefinition> &apps)
         if (!def.icon.isEmpty()) obj.insert(QStringLiteral("icon"), def.icon);
         if (!def.healthCheckUrl.isEmpty()) obj.insert(QStringLiteral("healthCheckUrl"), def.healthCheckUrl);
         if (def.healthTimeoutMs != 30000) obj.insert(QStringLiteral("healthTimeoutMs"), def.healthTimeoutMs);
+        if (def.debugPort > 0) obj.insert(QStringLiteral("debugPort"), def.debugPort);
         if (!def.autoKillOnClose) obj.insert(QStringLiteral("autoKillOnClose"), false);
         arr.append(obj);
     }

src/dialogs/EditMiniAppsDialog.cpp

@@ -16,10 +16,14 @@
 #include <QLabel>
 #include <QLineEdit>
 #include <QListWidget>
+#include <QMessageBox>
 #include <QPlainTextEdit>
 #include <QPushButton>
+#include <QSet>
 #include <QSpinBox>
 #include <QSplitter>
+#include <QTcpSocket>
+#include <QHostAddress>
 #include <QTimer>
 #include <QUuid>
 #include <QVBoxLayout>
@@ -134,6 +138,28 @@ EditMiniAppsDialog::EditMiniAppsDialog(MiniAppRegistry *registry,
     advLayout->addWidget(m_timeoutSpin);
     formLayout->addWidget(m_advancedGroup);
 
+    // Debug section (collapsible)
+    m_debugGroup = new QGroupBox(tr("Debug"), rightWidget);
+    m_debugGroup->setCheckable(true);
+    m_debugGroup->setChecked(false);
+    auto *debugLayout = new QVBoxLayout(m_debugGroup);
+    debugLayout->addWidget(new QLabel(tr("CDP Debug Port:"), m_debugGroup));
+    auto *portLayout = new QHBoxLayout;
+    m_debugPortSpin = new QSpinBox(m_debugGroup);
+    m_debugPortSpin->setRange(0, 65535);
+    m_debugPortSpin->setSpecialValueText(tr("Disabled"));
+    m_debugPortSpin->setToolTip(tr("0 = disabled. Set a port to enable Chrome DevTools Protocol debugging."));
+    portLayout->addWidget(m_debugPortSpin, 1);
+    m_randomPortBtn = new QPushButton(tr("Random"), m_debugGroup);
+    m_randomPortBtn->setToolTip(tr("Find an available port in range 9222-9322"));
+    portLayout->addWidget(m_randomPortBtn);
+    debugLayout->addLayout(portLayout);
+    m_portWarningLabel = new QLabel(m_debugGroup);
+    m_portWarningLabel->setStyleSheet(QStringLiteral("color: orange; font-size: 10px;"));
+    m_portWarningLabel->hide();
+    debugLayout->addWidget(m_portWarningLabel);
+    formLayout->addWidget(m_debugGroup);
+
     formLayout->addStretch();
 
     splitter->addWidget(leftWidget);
@@ -158,10 +184,12 @@ EditMiniAppsDialog::EditMiniAppsDialog(MiniAppRegistry *registry,
     connect(m_upBtn, &QPushButton::clicked, this, &EditMiniAppsDialog::onMoveUpClicked);
     connect(m_downBtn, &QPushButton::clicked, this, &EditMiniAppsDialog::onMoveDownClicked);
     connect(m_browseCwdBtn, &QPushButton::clicked, this, &EditMiniAppsDialog::onBrowseCwdClicked);
+    connect(m_randomPortBtn, &QPushButton::clicked, this, &EditMiniAppsDialog::onRandomPortClicked);
     connect(m_scopeCombo, QOverload<int>::of(&QComboBox::currentIndexChanged),
             this, &EditMiniAppsDialog::onScopeChanged);
     connect(m_urlEdit, &QLineEdit::textChanged, this, [this]() { m_validateTimer->start(); });
     connect(m_envEdit, &QPlainTextEdit::textChanged, this, [this]() { m_validateTimer->start(); });
+    connect(m_debugPortSpin, QOverload<int>::of(&QSpinBox::valueChanged), this, [this]() { m_validateTimer->start(); });
 
     connect(m_buttonBox, &QDialogButtonBox::accepted, this, [this]() {
         commitCurrentApp();
@@ -248,6 +276,7 @@ void EditMiniAppsDialog::commitCurrentApp()
     def.env = m_envEdit->toPlainText();
     def.healthCheckUrl = m_healthUrlEdit->text().trimmed();
     def.healthTimeoutMs = m_timeoutSpin->value() * 1000;
+    def.debugPort = m_debugGroup->isChecked() ? m_debugPortSpin->value() : 0;
 
     // Ensure ID
     if (def.id.isEmpty())
@@ -271,6 +300,8 @@ void EditMiniAppsDialog::loadApp(int row)
     m_envEdit->setEnabled(valid);
     m_healthUrlEdit->setEnabled(valid);
     m_timeoutSpin->setEnabled(valid);
+    m_debugPortSpin->setEnabled(valid);
+    m_randomPortBtn->setEnabled(valid);
 
     if (!valid) {
         m_nameEdit->clear();
@@ -280,8 +311,10 @@ void EditMiniAppsDialog::loadApp(int row)
         m_envEdit->clear();
         m_healthUrlEdit->clear();
         m_timeoutSpin->setValue(30);
+        m_debugPortSpin->setValue(0);
         m_urlWarningLabel->hide();
         m_envWarningLabel->hide();
+        m_portWarningLabel->hide();
         return;
     }
 
@@ -293,7 +326,10 @@ void EditMiniAppsDialog::loadApp(int row)
     m_envEdit->setPlainText(def.env);
     m_healthUrlEdit->setText(def.healthCheckUrl);
     m_timeoutSpin->setValue(def.healthTimeoutMs / 1000);
+    m_debugPortSpin->setValue(def.debugPort);
+    m_debugGroup->setChecked(def.debugPort > 0);
     m_urlWarningLabel->hide();
+    m_portWarningLabel->hide();
     validateFields();
 }
 
@@ -372,6 +408,26 @@ void EditMiniAppsDialog::validateFields()
         m_urlWarningLabel->hide();
     }
 
+    // Debug port conflict validation
+    const int port = m_debugPortSpin->value();
+    if (port > 0 && m_currentRow >= 0) {
+        bool conflict = false;
+        for (int i = 0; i < m_apps.size(); ++i) {
+            if (i == m_currentRow) continue;
+            if (m_apps[i].debugPort == port) {
+                m_portWarningLabel->setText(tr("Port %1 is already used by \"%2\"")
+                    .arg(port).arg(m_apps[i].name));
+                m_portWarningLabel->show();
+                conflict = true;
+                break;
+            }
+        }
+        if (!conflict)
+            m_portWarningLabel->hide();
+    } else {
+        m_portWarningLabel->hide();
+    }
+
     // Env validation (same as EditTasksDialog)
     const QString envText = m_envEdit->toPlainText();
     if (envText.trimmed().isEmpty()) {
@@ -405,3 +461,32 @@ void EditMiniAppsDialog::updateButtonStates()
     m_upBtn->setEnabled(row > 0);
     m_downBtn->setEnabled(row >= 0 && row < count - 1);
 }
+
+void EditMiniAppsDialog::onRandomPortClicked()
+{
+    // Collect ports already assigned to other apps in the list
+    QSet<int> usedPorts;
+    for (int i = 0; i < m_apps.size(); ++i) {
+        if (i == m_currentRow) continue;
+        if (m_apps[i].debugPort > 0)
+            usedPorts.insert(m_apps[i].debugPort);
+    }
+
+    // Scan 9222-9322 for an available port
+    for (int port = 9222; port <= 9322; ++port) {
+        if (usedPorts.contains(port))
+            continue;
+
+        // Bind-test: check if port is actually free on the system
+        QTcpSocket sock;
+        if (sock.bind(QHostAddress::LocalHost, static_cast<quint16>(port))) {
+            sock.close();
+            m_debugPortSpin->setValue(port);
+            return;
+        }
+    }
+
+    // All ports exhausted
+    QMessageBox::warning(this, tr("No Available Port"),
+        tr("No available port in range 9222-9322. Please enter a port manually."));
+}

src/dialogs/EditMiniAppsDialog.h

@@ -23,6 +23,7 @@ class QPlainTextEdit;
 class QPushButton;
 class QSpinBox;
 class QTimer;
+class QToolButton;
 
 class EditMiniAppsDialog : public QDialog
 {
@@ -41,6 +42,7 @@ private slots:
     void onMoveDownClicked();
     void onBrowseCwdClicked();
     void onScopeChanged(int index);
+    void onRandomPortClicked();
     void validateFields();
 
 private:
@@ -77,6 +79,12 @@ private slots:
     QLineEdit *m_healthUrlEdit = nullptr;
     QSpinBox *m_timeoutSpin = nullptr;
 
+    // Debug section
+    QGroupBox *m_debugGroup = nullptr;
+    QSpinBox *m_debugPortSpin = nullptr;
+    QPushButton *m_randomPortBtn = nullptr;
+    QLabel *m_portWarningLabel = nullptr;
+
     QLabel *m_urlWarningLabel = nullptr;
     QDialogButtonBox *m_buttonBox = nullptr;
 };