added data saving feature

python_app/webui/controller.py

@@ -13,9 +13,26 @@ from __future__ import annotations
 from typing import Protocol, runtime_checkable
 
 
+class WebActionError(Exception):
+    """A web-triggered desktop action failed, carrying the operator-facing reason.
+
+    Control methods run the matching desktop action *synchronously* and raise this
+    when that action reports an error (the same message the desktop would show), so
+    the HTTP layer can return it instead of a misleading "ok". Distinct from a plain
+    ``ValueError`` (rejected by web-side validation before the action even runs).
+    """
+
+
 @runtime_checkable
 class WebController(Protocol):
-    """Control + read surface the web layer needs; implemented by the Qt bridge."""
+    """Control + read surface the web layer needs; implemented by the Qt bridge.
+
+    Control methods are *synchronous*: each runs the corresponding desktop action on
+    the GUI thread and only returns once it has completed, raising
+    :class:`WebActionError` if the action surfaced an error. This is what lets the
+    browser show real failures (e.g. a save into an existing directory) instead of a
+    blind success.
+    """
 
     def start(self) -> None:
         """Start a continuous run (the desktop "Start" button)."""
@@ -26,6 +43,14 @@ class WebController(Protocol):
     def stop(self) -> None:
         """Stop the running pipeline (the desktop "Stop" button)."""
 
+    def start_recording(self, path: str, name: str, count: int) -> None:
+        """Start a run (if stopped) and record the next ``count`` measurements to disk.
+
+        ``path``/``name`` mirror the shared save destination fields (blank ``path``
+        keeps the configured one); ``count`` sets how many measurements are written.
+        Raises :class:`WebActionError` if the destination already exists.
+        """
+
     def capture_tmp_reference(self) -> None:
         """Capture and select a temporary reference (the desktop button)."""