rename ScenePartStateApi -> SceneMutationApi and clean up docs

Author: LKasianAnsys

src/ansys/visor/viewer/app/trame/local_app.py

@@ -26,20 +26,18 @@
 vtkObject.GlobalWarningDisplayOff()
 
 
-class ScenePartStateApi(Protocol):
+class SceneMutationApi(Protocol):
     """Structural type of the coordinator surface LocalApp calls.
 
     Typing only: there is no ``runtime_checkable`` decoration and no
     ``isinstance`` check anywhere against it.  Declaring it here rather than
     importing the scene keeps this module free of any scene type, so the
     injected object remains LocalApp's only route to the scene.
 
-    Not all of it is per-part, and the name is historical.  ``sync_camera``,
-    the three widget-state toggles and ``set_projection`` are scene-wide, and
-    they are declared here anyway: the one production injection site passes
-    the whole scene coordinator, so a second protocol would be the same object
-    under a second name.  Read this as the whole coordinator surface LocalApp calls, not only
-    the per-part part of it.
+    Covers both per-part mutations (visibility, opacity, colour, selection)
+    and scene-wide ones (camera sync, the widget-state toggles, projection,
+    cross-section plane).  The one production injection site passes the
+    whole scene coordinator, so this protocol describes that whole surface.
     """
 
     def set_part_visibility(self, node_id: int, visible: bool) -> None: ...
@@ -217,7 +215,7 @@ def __init__(
             standalone: bool = True,
             trame_logger: Logger | None = None,
             pick_geometry=None,
-            scene_part_state_api: ScenePartStateApi | None = None,
+            scene_mutation_api: SceneMutationApi | None = None,
     ):
         self.server = server
         # Callable to get the scene details in JSON format
@@ -226,10 +224,10 @@ def __init__(
         self._handle_save_state_response = handle_save_state_response
         # Callable for sub-geometry picking (optional)
         self._pick_geometry = pick_geometry
-        # Per-part visual state coordinator (see ScenePartStateApi).  The one
+        # Per-part visual state coordinator (see SceneMutationApi).  The one
         # production construction site always supplies it; it is optional so
         # that the class stays constructible without a scene.
-        self._scene_part_state_api = scene_part_state_api
+        self._scene_mutation_api = scene_mutation_api
         # logger for logging trame server lifecycle info
         self.__trame_logger = trame_logger
 
@@ -354,13 +352,13 @@ def perf_report_server_update(self, payload: dict):
     # body.
     # ------------------------------------------------------------------
 
-    def _part_state_api(self, trigger_name: str, payload: BaseModel) -> ScenePartStateApi | None:
+    def _part_state_api(self, trigger_name: str, payload: BaseModel) -> SceneMutationApi | None:
         """Return the injected coordinator, or ``None`` after logging."""
         logger.debug("[trigger] %s arrived: %s.", trigger_name, payload)
-        if self._scene_part_state_api is None:
+        if self._scene_mutation_api is None:
             logger.debug("%s: no scene part-state API injected; ignoring.", trigger_name)
             return None
-        return self._scene_part_state_api
+        return self._scene_mutation_api
 
     @trigger("set_part_visibility")
     @parse_payload(SetPartVisibilityPayload)
@@ -492,31 +490,14 @@ def sync_camera(self, payload) -> None:
     # ------------------------------------------------------------------
     # Widget-state triggers
     #
-    # Frontend -> Backend.  One trigger per server-tracked toggle.  Each
-    # carries the absolute target value the client's widget settled on,
-    # never a toggle and never a delta: the toolbar buttons are toggles, so
-    # the client reads its widget back after the local write and sends the
-    # result.  A message the client suppresses as redundant is therefore
-    # indistinguishable from one that set a value the server already held,
-    # and both are correct.
+    # Frontend -> Backend.  One trigger per server-tracked toggle. Each
+    # carries the absolute target value, not a delta, so a redundant
+    # message is indistinguishable from a no-op one, and both are fine.
+    # No ``origin`` field: unlike the camera, a toggle echo is idempotent.
     #
-    # No ``origin`` field (RS-1).  The camera needed one because a
-    # programmatic echo re-applied a *stale* camera over a newer one; a
-    # toggle echo carries the same boolean the server already holds, so the
-    # write is idempotent and the client's own widgets damp it with their
-    # value guards.  It is the same echo the per-part deliveries already
-    # produce on load.  Separating delivery from mutation is a later story's
-    # work, not this one's.
-    #
-    # Payloads are validated at this boundary by ``@parse_payload`` exactly
-    # as the per-part ones are.  The wire key is ``visible`` on the three
-    # visibility triggers and ``parallel`` on ``set_projection``; none carries
-    # a pydantic alias, snake_case and camelCase coinciding on all four.
-    #
-    # ``set_projection`` sits in this block because it arrives from the same
-    # toolbar and under the same absolute-value rule, but it is not a fourth
-    # toggle: the server keeps no projection field, the camera record holds
-    # it, and the coordinator re-serialises the camera as part of the write.
+    # ``set_projection`` lives here too: it is delivered the same way, but
+    # it writes the camera record's projection field rather than a toggle
+    # of its own.
     # ------------------------------------------------------------------
 
     @trigger("set_cross_section_visibility")

src/ansys/visor/viewer/app/visor_vtk_local.py

@@ -52,9 +52,9 @@ def _initialize_rendering(self, standalone: bool, trame_log_dir: str | None) ->
                 world_x,
                 world_y,
                 world_z: self._scene.pick_geometry(actor_wasm_id, cell_id, mode, world_x, world_y, world_z),
-            # The scene satisfies LocalApp's ScenePartStateApi protocol
+            # The scene satisfies LocalApp's SceneMutationApi protocol
             # structurally: the six per-part coordinator methods carry exactly
             # the names and signatures the triggers call.
-            scene_part_state_api=self._scene,
+            scene_mutation_api=self._scene,
         )
 

tests/unit/app/test_local_app.py

@@ -97,7 +97,7 @@ def mock_server():
 @pytest.fixture
 def api():
     """Stand-in for the injected per-part coordinator object."""
-    return MagicMock(name="scene_part_state_api")
+    return MagicMock(name="scene_mutation_api")
 
 
 @pytest.fixture
@@ -108,7 +108,7 @@ def app(mock_server, api):
         get_scene_details_json=MagicMock(),
         handle_save_state_response=MagicMock(),
         standalone=True,
-        scene_part_state_api=api,
+        scene_mutation_api=api,
     )
 
 

tests/unit/app/test_local_app_set_projection.py

@@ -72,7 +72,7 @@ def mock_server():
 @pytest.fixture
 def api():
     """Stand-in for the injected scene coordinator."""
-    return MagicMock(name="scene_part_state_api")
+    return MagicMock(name="scene_mutation_api")
 
 
 @pytest.fixture
@@ -83,7 +83,7 @@ def app(mock_server, api):
         get_scene_details_json=MagicMock(),
         handle_save_state_response=MagicMock(),
         standalone=True,
-        scene_part_state_api=api,
+        scene_mutation_api=api,
     )
 
 

tests/unit/app/test_local_app_sync_camera.py

@@ -91,7 +91,7 @@ def mock_server():
 @pytest.fixture
 def api():
     """Stand-in for the injected scene coordinator."""
-    return MagicMock(name="scene_part_state_api")
+    return MagicMock(name="scene_mutation_api")
 
 
 @pytest.fixture
@@ -102,7 +102,7 @@ def app(mock_server, api):
         get_scene_details_json=MagicMock(),
         handle_save_state_response=MagicMock(),
         standalone=True,
-        scene_part_state_api=api,
+        scene_mutation_api=api,
     )
 
 

tests/unit/app/test_local_app_widget_triggers.py

@@ -68,7 +68,7 @@ def mock_server():
 @pytest.fixture
 def api():
     """Stand-in for the injected scene coordinator."""
-    return MagicMock(name="scene_part_state_api")
+    return MagicMock(name="scene_mutation_api")
 
 
 @pytest.fixture
@@ -79,7 +79,7 @@ def app(mock_server, api):
         get_scene_details_json=MagicMock(),
         handle_save_state_response=MagicMock(),
         standalone=True,
-        scene_part_state_api=api,
+        scene_mutation_api=api,
     )
 
 

tests/unit/app/test_visor_vtk_local.py

@@ -560,8 +560,8 @@ def test_local_app_receives_the_scene_as_the_part_state_api(local_app_call):
     """The scene itself is injected, not a wrapper or a set of lambdas."""
     call, scene, instance = local_app_call
 
-    assert call.kwargs["scene_part_state_api"] is scene
-    assert call.kwargs["scene_part_state_api"] is instance._scene
+    assert call.kwargs["scene_mutation_api"] is scene
+    assert call.kwargs["scene_mutation_api"] is instance._scene
 
 
 def test_local_app_still_receives_the_pre_existing_arguments(local_app_call):