web UI added and refactoring done

python_app/webui/controller.py

@@ -0,0 +1,42 @@
+"""The Qt-free contract the web layer depends on.
+
+The web layer (``app``/``routes``/``streaming``) is deliberately free of any Qt
+or hardware knowledge: it talks only to a :class:`WebController`. The embedded
+bridge in ``gui/controllers/app_window_web_mixin.py`` implements this protocol by
+forwarding control actions to the AppWindow's *existing* buttons and exposing
+read-only snapshots — so the very same desktop logic backs the browser, with no
+duplicated control flow.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WebController(Protocol):
+    """Control + read surface the web layer needs; implemented by the Qt bridge."""
+
+    def start(self) -> None:
+        """Start a continuous run (the desktop "Start" button)."""
+
+    def single_capture(self) -> None:
+        """Run a single-capture acquisition (the desktop "Single Capture" button)."""
+
+    def stop(self) -> None:
+        """Stop the running pipeline (the desktop "Stop" button)."""
+
+    def capture_tmp_reference(self) -> None:
+        """Capture and select a temporary reference (the desktop button)."""
+
+    def apply_live_settings(self, fields: dict) -> list:
+        """Apply live processor settings; returns the current settings schema."""
+
+    def current_live_settings(self) -> list:
+        """Return the live-settings schema (built from the Qt widgets)."""
+
+    def status(self) -> dict:
+        """Return a snapshot of pipeline/run state."""
+
+    def peek_frame(self) -> dict | None:
+        """Return the latest rendered-plot frame (PNG of the Qt plot), or ``None``."""