Wire USB Sharing panel to the live WebRTC viewer session

Add a Source selector (Local loopback / Remote WebRTC) to the panel's use
section. When Remote is selected, List / Open run against the live WebRTC
viewer's host via a new registry.webrtc_usb_client() accessor; both sources
share the same list_devices/open API so the actions stay source-agnostic.
The provider is injectable for testing. i18n across four languages; docs
updated; import je_auto_control stays Qt-free and aiortc-free.

Author: JE-Chen

docs/source/Eng/doc/operations_layer/usb_passthrough_operator_guide.rst

@@ -279,13 +279,13 @@ What is *not* shipped yet
   one (a descriptor read proves the full stack). The *USB Browser* tab's
   *Open* button now also works against a **localhost** target via the
   same loopback path.
-- Cross-machine transport is now wired: the WebRTC host creates a
-  ``usb`` DataChannel and the viewer exposes ``viewer.usb_client()``
-  (a ``UsbChannelClient`` with ``list_devices`` / ``open`` / ``resume``).
-  Drive it from Python today over a live WebRTC session. The simple
-  *USB Browser* / *USB Sharing* panels still use the local loopback +
-  REST paths; auto-wiring those panels to a live WebRTC viewer session
-  is the remaining GUI integration step.
+- Cross-machine is fully wired: the WebRTC host creates a ``usb``
+  DataChannel and the viewer exposes ``viewer.usb_client()`` (a
+  ``UsbChannelClient`` with ``list_devices`` / ``open`` / ``resume``).
+  The *USB Sharing* panel has a **Source** selector — pick *Remote
+  (WebRTC)* and the List / Open buttons run against the live WebRTC
+  viewer's host (via ``registry.webrtc_usb_client()``); pick *Local
+  (loopback)* for same-machine use. You can also drive it from Python.
 - Windows WinUSB and macOS IOKit transfer paths are written but not yet
   validated against real hardware. Do not use in production until the
   Phase 2e hardware test matrix passes.

docs/source/Zh/doc/operations_layer/usb_passthrough_operator_guide.rst

@@ -258,12 +258,12 @@ OPEN 後 host 鍵盤停止運作                   Linux：HID 裝置被 claim 
   做 ACL 允許／封鎖；右側經 in-process channel 列出分享裝置並 *開啟*
   其中一個（讀描述元即證明整條堆疊運作）。*USB Browser* 分頁的 *Open*
   按鈕現在對 **localhost** 目標也會走同一條 loopback 路徑。
-- 跨機器 transport 已串接：WebRTC host 會建立 ``usb`` DataChannel，
-  viewer 以 ``viewer.usb_client()`` 暴露 ``UsbChannelClient``\ （含
-  ``list_devices`` / ``open`` / ``resume``\ ）。今天即可在 WebRTC session
-  上從 Python 驅動。簡易的 *USB Browser* / *USB 分享* 面板目前仍走本機
-  loopback + REST；把面板自動接到 live WebRTC viewer session 是剩餘的
-  GUI 整合步驟。
+- 跨機器已完整串接：WebRTC host 建立 ``usb`` DataChannel，viewer 以
+  ``viewer.usb_client()`` 暴露 ``UsbChannelClient``\ （含 ``list_devices``
+  / ``open`` / ``resume``\ ）。*USB 分享* 面板有 **來源** 下拉：選
+  *遠端(WebRTC)* 時 List / Open 會對 live WebRTC viewer 的主機操作
+  （經 ``registry.webrtc_usb_client()``\ ）；選 *本機(loopback)* 則走同機。
+  亦可從 Python 驅動。
 - Windows WinUSB 與 macOS IOKit 的 transfer 路徑已寫但尚未對實體硬體
   驗證。在 Phase 2e 硬體測試矩陣通過前請勿用於 production。
 - Phase 2e 外部安全審查尚未簽核；feature flag 必須維持顯式 opt-in。

je_auto_control/gui/language_wrapper/english.py

@@ -156,6 +156,10 @@
     "usb_share_acl_imported": "Imported {count} rule(s).",
     "usb_share_acl_import_failed": "ACL I/O failed: {error}",
     "usb_share_auto_refresh": "Auto-refresh (hotplug)",
+    "usb_share_source_label": "Source:",
+    "usb_share_source_local": "Local (loopback)",
+    "usb_share_source_remote": "Remote (WebRTC)",
+    "usb_share_no_webrtc": "No live WebRTC session — connect a WebRTC viewer first.",
 
     # Inspector tab
     "inspector_metrics_group": "Rolling metrics",

je_auto_control/gui/language_wrapper/japanese.py

@@ -154,6 +154,10 @@
     "usb_share_acl_imported": "{count} 件のルールをインポートしました。",
     "usb_share_acl_import_failed": "ACL 入出力に失敗：{error}",
     "usb_share_auto_refresh": "自動更新(ホットプラグ)",
+    "usb_share_source_label": "ソース：",
+    "usb_share_source_local": "ローカル(loopback)",
+    "usb_share_source_remote": "リモート(WebRTC)",
+    "usb_share_no_webrtc": "ライブ WebRTC セッションがありません — 先に WebRTC viewer に接続してください。",
 
     # 監視タブ
     "inspector_metrics_group": "集約メトリクス",

je_auto_control/gui/language_wrapper/simplified_chinese.py

@@ -145,6 +145,10 @@
     "usb_share_acl_imported": "已导入 {count} 条规则。",
     "usb_share_acl_import_failed": "ACL 读写失败：{error}",
     "usb_share_auto_refresh": "自动刷新(热插拔)",
+    "usb_share_source_label": "来源：",
+    "usb_share_source_local": "本机(loopback)",
+    "usb_share_source_remote": "远程(WebRTC)",
+    "usb_share_no_webrtc": "没有 live WebRTC session — 请先连接 WebRTC viewer。",
 
     # 包监测分页
     "inspector_metrics_group": "汇总指标",

je_auto_control/gui/language_wrapper/traditional_chinese.py

@@ -146,6 +146,10 @@
     "usb_share_acl_imported": "已匯入 {count} 條規則。",
     "usb_share_acl_import_failed": "ACL 讀寫失敗：{error}",
     "usb_share_auto_refresh": "自動刷新(熱插拔)",
+    "usb_share_source_label": "來源：",
+    "usb_share_source_local": "本機(loopback)",
+    "usb_share_source_remote": "遠端(WebRTC)",
+    "usb_share_no_webrtc": "沒有 live WebRTC session — 請先連線 WebRTC viewer。",
 
     # 封包監測分頁
     "inspector_metrics_group": "彙整指標",

je_auto_control/gui/usb_passthrough_panel.py

@@ -21,9 +21,9 @@
 
 from PySide6.QtCore import QObject, QThread, QTimer, Signal
 from PySide6.QtWidgets import (
-    QCheckBox, QFileDialog, QGroupBox, QHBoxLayout, QHeaderView, QLabel,
-    QLineEdit, QMessageBox, QPushButton, QTableWidget, QTableWidgetItem,
-    QVBoxLayout, QWidget,
+    QCheckBox, QComboBox, QFileDialog, QGroupBox, QHBoxLayout, QHeaderView,
+    QLabel, QLineEdit, QMessageBox, QPushButton, QTableWidget,
+    QTableWidgetItem, QVBoxLayout, QWidget,
 )
 
 from je_auto_control.gui._i18n_helpers import TranslatableMixin
@@ -76,15 +76,22 @@ class UsbPassthroughPanel(TranslatableMixin, QWidget):
     def __init__(self, parent: Optional[QWidget] = None, *,
                  acl: Optional[UsbAcl] = None,
                  loopback_factory: Optional[Callable[[], UsbLoopback]] = None,
+                 remote_client_provider: Optional[
+                     Callable[[], Optional[Any]]
+                 ] = None,
                  ) -> None:
         super().__init__(parent)
         self._tr_init()
         self._acl = acl if acl is not None else UsbAcl()
         self._loopback_factory = loopback_factory or self._default_loopback
+        self._remote_client_provider = (
+            remote_client_provider or _default_remote_client
+        )
         self._loopback: Optional[UsbLoopback] = None
         self._thread: Optional[QThread] = None
         self._host_badge = _StatusBadge()
         self._viewer_status = QLabel("")
+        self._source_combo = QComboBox()
         self._auto_check = QCheckBox()
         self._auto_check.toggled.connect(self._on_auto_toggled)
         self._hotplug_timer = QTimer(self)
@@ -97,6 +104,7 @@ def __init__(self, parent: Optional[QWidget] = None, *,
         self._remote_token = QLineEdit()
         self._remote_token.setEchoMode(QLineEdit.EchoMode.Password)
         self._build_layout()
+        self._populate_source_combo()
         self._apply_local_headers()
         self._apply_shared_headers()
         self._refresh_local_devices()
@@ -161,6 +169,10 @@ def _build_viewer_section(self) -> QWidget:
         intro = self._tr(QLabel(), "usb_share_intro")
         intro.setWordWrap(True)
         layout.addWidget(intro)
+        source_row = QHBoxLayout()
+        source_row.addWidget(self._tr(QLabel(), "usb_share_source_label"))
+        source_row.addWidget(self._source_combo, stretch=1)
+        layout.addLayout(source_row)
         layout.addWidget(self._shared_table, stretch=1)
         use_row = QHBoxLayout()
         list_btn = self._tr(QPushButton(), "usb_share_fetch_shared")
@@ -204,8 +216,18 @@ def _apply_shared_headers(self) -> None:
             _t("usb_share_col_product"), _t("usb_share_col_serial"),
         ])
 
+    def _populate_source_combo(self) -> None:
+        index = max(0, self._source_combo.currentIndex())
+        self._source_combo.blockSignals(True)
+        self._source_combo.clear()
+        self._source_combo.addItem(_t("usb_share_source_local"))
+        self._source_combo.addItem(_t("usb_share_source_remote"))
+        self._source_combo.setCurrentIndex(index)
+        self._source_combo.blockSignals(False)
+
     def retranslate(self) -> None:
         TranslatableMixin.retranslate(self)
+        self._populate_source_combo()
         self._apply_local_headers()
         self._apply_shared_headers()
         self._refresh_host_badge()
@@ -330,15 +352,40 @@ def _import_acl(self) -> None:
         )
         self._refresh_local_devices()
 
-    # --- use (loopback) ----------------------------------------------------
+    # --- use (loopback or live WebRTC) -------------------------------------
+
+    def _source_is_remote(self) -> bool:
+        return self._source_combo.currentIndex() == 1
+
+    def _active_use_client(self) -> Any:
+        """Return the client for the selected source, or raise a friendly error.
+
+        Both the loopback bundle and the WebRTC ``UsbChannelClient``
+        expose ``list_devices`` and ``open`` with the same signatures, so
+        the use actions are source-agnostic.
+        """
+        if self._source_is_remote():
+            client = self._remote_client_provider()
+            if client is None:
+                raise RuntimeError(_t("usb_share_no_webrtc"))
+            return client
+        if self._loopback is None:
+            raise RuntimeError(_t("usb_share_enable_first"))
+        return self._loopback
+
+    def _use_client_or_warn(self) -> Any:
+        try:
+            return self._active_use_client()
+        except RuntimeError as error:
+            self._info(str(error))
+            return None
 
     def _list_shared(self) -> None:
-        loop = self._loopback
-        if loop is None:
-            self._info(_t("usb_share_enable_first"))
+        client = self._use_client_or_warn()
+        if client is None:
             return
         self._viewer_status.setText(_t("usb_share_listing"))
-        self._run_async(loop.list_devices, self._apply_shared, self._fail)
+        self._run_async(client.list_devices, self._apply_shared, self._fail)
 
     def _apply_shared(self, devices: List[dict]) -> None:
         self._viewer_status.setText(
@@ -354,9 +401,8 @@ def _apply_shared(self, devices: List[dict]) -> None:
                 self._shared_table.setItem(row, col, QTableWidgetItem(str(text)))
 
     def _open_selected(self) -> None:
-        loop = self._loopback
-        if loop is None:
-            self._info(_t("usb_share_enable_first"))
+        client = self._use_client_or_warn()
+        if client is None:
             return
         row = _selected_row(self._shared_table)
         if row is None:
@@ -369,7 +415,7 @@ def _open_selected(self) -> None:
             _t("usb_share_opening").format(vid=vid, pid=pid),
         )
         self._run_async(
-            lambda: _probe_device(loop, vid, pid, serial),
+            lambda: _probe_device(client, vid, pid, serial),
             lambda descriptor: self._opened(vid, pid, descriptor),
             self._fail,
         )
@@ -458,10 +504,23 @@ def _selected_row(table: QTableWidget) -> Optional[int]:
     return rows[0] if rows else None
 
 
-def _probe_device(loop: UsbLoopback, vid: str, pid: str,
+def _default_remote_client() -> Optional[Any]:
+    """Return the live WebRTC viewer's USB client, or None if unavailable."""
+    try:
+        from je_auto_control.utils.remote_desktop.registry import registry
+    except ImportError:
+        return None
+    return registry.webrtc_usb_client()
+
+
+def _probe_device(client: Any, vid: str, pid: str,
                   serial: Optional[str]) -> bytes:
-    """Open the device, read its descriptor as a liveness proof, close."""
-    handle = loop.open(vendor_id=vid, product_id=pid, serial=serial)
+    """Open the device, read its descriptor as a liveness proof, close.
+
+    ``client`` is either a :class:`UsbLoopback` or a WebRTC
+    ``UsbChannelClient`` — both expose the same ``open`` signature.
+    """
+    handle = client.open(vendor_id=vid, product_id=pid, serial=serial)
     try:
         return handle.control_transfer(
             bm_request_type=_DESC_REQUEST_TYPE, b_request=_DESC_REQUEST,

je_auto_control/utils/remote_desktop/registry.py

@@ -352,5 +352,18 @@ def webrtc_viewer_status(self) -> Dict[str, Any]:
             "authenticated": getattr(viewer, "authenticated", False),
         }
 
+    def webrtc_usb_client(self):
+        """Return the live WebRTC viewer's USB passthrough client, or None.
+
+        The viewer exposes ``usb_client()`` once the host has opened the
+        ``usb`` DataChannel. Returns None when no WebRTC viewer is active
+        or the channel hasn't been negotiated yet.
+        """
+        viewer = self._webrtc_viewer
+        if viewer is None:
+            return None
+        getter = getattr(viewer, "usb_client", None)
+        return getter() if callable(getter) else None
+
 
 registry = _RemoteDesktopRegistry()

test/unit_test/headless/test_usb_passthrough_panel.py

@@ -133,6 +133,60 @@ def test_panel_hotplug_toggle_starts_and_stops(qapp, tmp_path):
         panel.deleteLater()
 
 
+def test_panel_remote_source_uses_provider(qapp, tmp_path):
+    """When 'Remote (WebRTC)' is selected, the panel routes to the
+    injected provider's client instead of the local loopback."""
+    backend = FakeUsbBackend(devices=[_SAMPLE])
+    acl = UsbAcl(path=tmp_path / "acl.json")
+    acl.add_rule(AclRule(vendor_id="1050", product_id="0407", allow=True))
+    remote = UsbLoopback(backend=backend, acl=acl, viewer_id="remote")
+    panel = _panel_mod.UsbPassthroughPanel(
+        acl=UsbAcl(path=tmp_path / "host_acl.json"),
+        loopback_factory=lambda: UsbLoopback(
+            backend=FakeUsbBackend(devices=[]), acl=acl,
+        ),
+        remote_client_provider=lambda: remote,
+    )
+    try:
+        # Index 1 == "Remote (WebRTC)".
+        panel._source_combo.setCurrentIndex(1)
+        client = panel._active_use_client()
+        assert client is remote
+        assert [d["vendor_id"] for d in client.list_devices()] == ["1050"]
+    finally:
+        remote.close()
+        panel.deleteLater()
+
+
+def test_panel_remote_source_without_session_warns(qapp, tmp_path):
+    panel = _panel_mod.UsbPassthroughPanel(
+        acl=UsbAcl(path=tmp_path / "acl.json"),
+        loopback_factory=lambda: UsbLoopback(
+            backend=FakeUsbBackend(devices=[]),
+            acl=UsbAcl(path=tmp_path / "acl.json"),
+        ),
+        remote_client_provider=lambda: None,  # no live WebRTC session
+    )
+    try:
+        panel._source_combo.setCurrentIndex(1)
+        import pytest as _pytest
+        with _pytest.raises(RuntimeError):
+            panel._active_use_client()
+    finally:
+        panel.deleteLater()
+
+
+def test_panel_local_source_is_default(qapp, tmp_path):
+    panel, _acl = _make_panel(qapp, tmp_path)
+    try:
+        assert panel._source_combo.currentIndex() == 0
+        panel._enable_sharing()
+        assert panel._active_use_client() is panel._loopback
+    finally:
+        panel._disable_sharing()
+        panel.deleteLater()
+
+
 def test_panel_export_import_acl_round_trip(qapp, tmp_path):
     panel, acl = _make_panel(qapp, tmp_path)
     try:

test/unit_test/headless/test_usb_registry_client.py

@@ -0,0 +1,33 @@
+"""registry.webrtc_usb_client() exposes the live WebRTC viewer's USB client."""
+from je_auto_control.utils.remote_desktop.registry import registry
+
+
+def test_webrtc_usb_client_none_when_no_viewer():
+    # No WebRTC viewer is active in a fresh process.
+    registry._webrtc_viewer = None  # noqa: SLF001  test setup
+    assert registry.webrtc_usb_client() is None
+
+
+def test_webrtc_usb_client_delegates_to_viewer():
+    sentinel = object()
+
+    class _FakeViewer:
+        def usb_client(self):
+            return sentinel
+
+    registry._webrtc_viewer = _FakeViewer()  # noqa: SLF001  test setup
+    try:
+        assert registry.webrtc_usb_client() is sentinel
+    finally:
+        registry._webrtc_viewer = None  # noqa: SLF001  cleanup
+
+
+def test_webrtc_usb_client_tolerates_viewer_without_method():
+    class _OldViewer:
+        pass
+
+    registry._webrtc_viewer = _OldViewer()  # noqa: SLF001  test setup
+    try:
+        assert registry.webrtc_usb_client() is None
+    finally:
+        registry._webrtc_viewer = None  # noqa: SLF001  cleanup