feat: implement canvas state management and visual state for valves

Author: jirhiker

AGENTS.md

@@ -19,6 +19,35 @@ Pychron is a long-lived scientific application with mixed concerns:
 
 Favor conservative, low-regression changes over broad rewrites.
 
+Repo Map
+========
+
+Start with the user-facing subsystem and only expand outward as needed.
+
+- application/bootstrap and plugin wiring:
+  - `launchers/`
+  - `pychron/applications`
+  - `pychron/envisage`
+- experiment execution and scripting:
+  - `pychron/experiment`
+  - `pychron/pyscripts`
+- data reduction, processing, and pipeline work:
+  - `pychron/pipeline`
+  - `pychron/processing`
+- DVC and repository-backed persistence:
+  - `pychron/dvc`
+- hardware, instruments, and control surfaces:
+  - `pychron/hardware`
+  - `pychron/lasers`
+  - `pychron/extraction_line`
+  - `pychron/spectrometer`
+  - `pychron/furnace`
+- shared foundations used across many subsystems:
+  - `pychron/core`
+  - `pychron/database`
+  - `pychron/paths.py`
+  - `pychron/globals.py`
+
 Working Rules
 =============
 
@@ -28,28 +57,69 @@ Working Rules
 - Expect the repo to contain legacy modules, experimental files, and partial
   migrations; patch the active path you are changing instead of trying to
   normalize the whole tree in one pass.
+- If a subsystem repeatedly needs specialized guidance, add a nested
+  `AGENTS.md` in that directory instead of overloading the root file. Only do
+  this when the local conventions are stable and materially different from the
+  repo-wide defaults.
 
 Code Changes
 ============
 
 - Prefer focused edits over opportunistic refactors.
+- Add type annotations to any function you touch. If a full signature annotation
+  would force broader churn, annotate the parameters and return value needed for
+  the current edit and keep the rest of the change scoped.
+- When debugging a bug or regression, add targeted instrumentation early to
+  confirm control flow, state transitions, inputs, and external responses before
+  attempting speculative fixes.
 - When replacing debug `print()` calls in runtime code, use the repo's existing
   logging style:
   - `Loggable` subclasses use `self.debug(...)`, `self.warning(...)`, etc.
   - other modules typically use `new_logger(...)` or a local logger
+- Prefer narrow, hypothesis-driven instrumentation near the suspected failure
+  boundary first: UI actions, task/plugin entrypoints, hardware I/O, experiment
+  state changes, and DVC/database calls.
+- Remove temporary instrumentation before finishing unless it provides ongoing
+  operational value. Do not broaden a debugging task into repo-wide logging
+  cleanup or leave noisy logs in hot paths without justification.
 - Preserve `if __name__ == "__main__":` demo blocks unless the task is to remove
   them. Do not treat demo code as runtime code.
 - Keep imports modern in active Qt code. Avoid reintroducing `PySide`,
   `traitsui.qt4`, or `pyface.ui.qt4` in touched files.
 - Use ASCII unless the file already requires other characters.
 
+Triage Workflow
+===============
+
+- Identify the user-facing subsystem first, then trace inward to the smallest
+  active module that implements the behavior.
+- Check for nearby tests before editing. Prefer colocated tests under
+  `pychron/*/tests`, `test/`, or a subsystem-specific test package before
+  reaching for broad suites.
+- Favor the path already exercised by launchers, plugins, tasks, or currently
+  referenced docs. Do not normalize parallel legacy code paths unless the task
+  explicitly requires it.
+- Use documentation to disambiguate architecture, startup flow, or workflow
+  expectations, but do not widen the implementation scope just because related
+  docs exist.
+- When adding a nested `AGENTS.md`, keep it limited to local setup, testing,
+  or architectural traps. Do not duplicate root policies unless the local file
+  is intentionally narrowing them for that subtree.
+
 Testing
 =======
 
 - Run the narrowest useful verification for the files you touched.
 - Good default checks:
   - `python -m py_compile <files>`
   - `python -m unittest <module>`
+- Testing heuristics for this repo:
+  - prefer module-level or package-level checks before full-suite runs
+  - search for colocated tests under `pychron/*/tests` before using aggregate
+    runners such as `pychron/test_suite.py`
+  - if a change touches Qt, Traits, hardware, or external services, say what is
+    unavailable and fall back to source-level verification when runtime checks
+    are not feasible
 - If a subsystem depends on Qt, Traits, or hardware services that are unavailable,
   say so explicitly and fall back to source-level verification.
 
@@ -59,6 +129,11 @@ Docs And Workflow
 - Keep `README.md` high signal. It should explain what the repo is, where docs
   live, and how development works now.
 - Prefer documenting branch/release policy in `docs/dev_guide/`.
+- Useful orientation documents:
+  - `README.md`
+  - `docs/dev_guide/index.rst`
+  - `docs/dev_guide/running_pychron.rst`
+  - `docs/dev_guide/git_workflow.rst`
 - When release workflow changes, keep these files aligned:
   - `docs/dev_guide/git_workflow.rst`
   - `docs/dev_guide/repository_settings.rst`

pychron/canvas/canvas2D/extraction_line_canvas2D.py

@@ -17,8 +17,10 @@
 # ============= enthought library imports =======================
 import os
 
+from enable.api import Interactor
 from enable.enable_traits import Pointer
 from pyface.action.menu_manager import MenuManager
+from pyface.qt.QtCore import QPoint
 from pyface.qt.QtGui import QToolTip
 from traits.api import Any, Str, on_trait_change, Bool, List
 from traitsui.menu import Action
@@ -60,6 +62,17 @@ class ExtractionLineAction(Action):
     chamber = Str
 
 
+class ExtractionLineMenuTool(Interactor):
+    parent = Any
+
+    def normal_right_down(self, event):
+        if event.handled:
+            return
+
+        if self.parent is not None:
+            self.parent.show_menu(event)
+
+
 class ExtractionLineCanvas2D(SceneCanvas):
     """ """
 
@@ -96,6 +109,8 @@ class ExtractionLineCanvas2D(SceneCanvas):
 
     _px = None
     _py = None
+    canvas_state = Any
+    _context_menu = Any
 
     def __init__(self, *args, **kw):
         super(ExtractionLineCanvas2D, self).__init__(*args, **kw)
@@ -105,6 +120,7 @@ def __init__(self, *args, **kw):
         )
         overlay = ExtractionLineInfoOverlay(tool=tool, component=self)
         self.tool = tool
+        self.tools.append(ExtractionLineMenuTool(component=self, parent=self))
         self.tools.append(tool)
         self.overlays.append(overlay)
 
@@ -130,6 +146,27 @@ def update_switch_state(self, name, nstate, refresh=True, mode=None):
             if refresh:
                 self.invalidate_and_redraw()
 
+    def apply_canvas_state(self, state, refresh=True):
+        self.canvas_state = state
+        for name, valve_state in state.valves.items():
+            self.set_valve_visual_state(name, valve_state, refresh=False)
+
+        if refresh:
+            self.invalidate_and_redraw()
+
+    def set_valve_visual_state(self, name, visual_state, refresh=True):
+        switch = self._get_switch_by_name(name)
+        if switch is None or visual_state is None:
+            return
+
+        if hasattr(switch, "apply_visual_state"):
+            switch.apply_visual_state(visual_state)
+        else:
+            switch.state = visual_state.is_open
+
+        if refresh:
+            self.invalidate_and_redraw()
+
     def update_switch_owned_state(self, name, owned):
         switch = self._get_switch_by_name(name)
         if switch is not None:
@@ -184,10 +221,10 @@ def normal_mouse_move(self, event):
             self.event_state = "select"
             if item != self.active_item:
                 self.active_item = item
+                if self.manager:
+                    self.manager.set_active_canvas_item(item)
             if isinstance(item, (BaseValve, Switch)):
                 event.window.set_pointer(self.select_pointer)
-                if self.manager:
-                    self.manager.set_selected_explanation_item(item)
         else:
             event.window.control.setToolTip("")
             QToolTip.hideText()
@@ -196,7 +233,7 @@ def normal_mouse_move(self, event):
             self.event_state = "normal"
             event.window.set_pointer(self.normal_pointer)
             if self.manager:
-                self.manager.set_selected_explanation_item(None)
+                self.manager.set_active_canvas_item(None)
 
     def select_mouse_move(self, event):
         """ """
@@ -211,6 +248,18 @@ def select_mouse_move(self, event):
     def select_right_down(self, event):
         item = self.active_item
         if item is not None:
+            if self.manager and isinstance(item, (BaseValve, Switch)):
+                self.manager.set_selected_explanation_item(item)
+            self._show_menu(event, item)
+        event.handled = True
+
+    def show_menu(self, event):
+        item = self._over_item(event)
+        if item is not None:
+            self.active_item = item
+            if self.manager and isinstance(item, (BaseValve, Switch)):
+                self.manager.set_active_canvas_item(item)
+                self.manager.set_selected_explanation_item(item)
             self._show_menu(event, item)
         event.handled = True
 
@@ -243,6 +292,9 @@ def set_state(state):
         if item is None:
             return
 
+        if self.manager and isinstance(item, (BaseValve, Switch)):
+            self.manager.set_selected_explanation_item(item)
+
         if self.edit_mode:
             self.event_state = "drag"
             event.window.set_pointer(self.drag_pointer)
@@ -348,9 +400,8 @@ def drag_mouse_leave(self, event):
     def on_lock(self):
         item = self._active_item
         if item:
-            item.soft_lock = lock = not item.soft_lock
+            lock = not item.soft_lock
             self.manager.set_software_lock(item.name, lock)
-            self.request_redraw()
 
     def on_force_close(self):
         self._force_actuate(self.manager.close_valve, False)
@@ -414,31 +465,45 @@ def _action_factory(self, name, func, klass=None, **kw):
 
     def _show_menu(self, event, obj):
         actions = []
+        allow_locking = self.manager.mode != "client" or globalv.client_only_locking
+        allow_force = self.manager.mode != "client" and self.force_actuate_enabled
 
-        if self.manager.mode != "client" or not globalv.client_only_locking:
-            # print self.active_item, isinstance(self.active_item, Switch)
-            # if isinstance(self.active_item, Switch):
-            if isinstance(self.active_item, BaseValve):
-                t = "Lock"
-                if obj.soft_lock:
-                    t = "Unlock"
+        if allow_locking and isinstance(obj, BaseValve):
+            t = "Lock"
+            if obj.soft_lock:
+                t = "Unlock"
 
-                action = self._action_factory(t, "on_lock")
-                actions.append(action)
+            action = self._action_factory(t, "on_lock")
+            actions.append(action)
 
-            if self.force_actuate_enabled:
-                action = self._action_factory("Force Close", "on_force_close")
-                actions.append(action)
+        if allow_force:
+            action = self._action_factory("Force Close", "on_force_close")
+            actions.append(action)
 
-                action = self._action_factory("Force Open", "on_force_open")
-                actions.append(action)
+            action = self._action_factory("Force Open", "on_force_open")
+            actions.append(action)
 
         if actions:
             menu_manager = MenuManager(*actions)
 
             self._active_item = self.active_item
-            menu = menu_manager.create_menu(event.window.control, None)
-            menu.show()
+            control = event.window.control
+            menu = menu_manager.create_menu(control, None)
+            self._context_menu = menu
+
+            global_pos = getattr(event, "global_pos", None)
+            if global_pos is None and control is not None:
+                size = control.size()
+                global_pos = control.mapToGlobal(
+                    QPoint(int(event.x), int(size.height() - event.y))
+                )
+
+            if global_pos is not None and hasattr(menu, "exec_"):
+                menu.exec_(global_pos)
+            elif hasattr(menu, "exec_"):
+                menu.exec_()
+            else:
+                menu.show()
 
 
 # ============= EOF ====================================

pychron/canvas/canvas2D/scene/primitives/base.py

@@ -216,7 +216,14 @@ def map_dimension(self, d, keep_square=False):
 
     def get_bounds(self):
         """Get bounding box as (x, y, x2, y2)."""
-        key = (self.x, self.y, self.width, self.height)
+        canvas_bounds = None
+        if self.canvas is not None:
+            canvas_bounds = tuple(self.canvas.bounds) if self.canvas.bounds is not None else None
+            if self.bounds != canvas_bounds:
+                self._layout_needed = True
+                self.bounds = canvas_bounds
+
+        key = (self.x, self.y, self.width, self.height, canvas_bounds)
         if self._cached_bounds is None or self._cached_bounds_key != key:
             x, y = self.get_xy(clear_layout_needed=False)
             w, h = self.get_wh()

pychron/canvas/canvas2D/scene/primitives/rounded.py

@@ -29,6 +29,11 @@
 )
 
 
+def calc_border_gap_half_width(border_width, connection):
+    """Trim border cutouts to the connector interior instead of the full span."""
+    return max((connection.width - border_width) / 2.0, 1)
+
+
 def rounded_rect(gc, x, y, width, height, corner_radius):
     with gc:
         gc.translate_ctm(x, y)  # draw a rounded rectangle
@@ -115,7 +120,7 @@ def _render_border(self, gc, x, y, width, height, use_border_gaps=True):
             if self.use_border_gaps and use_border_gaps:
                 # with gc:
                 for t, c in self.connections:
-                    cw4 = c.width / 2
+                    cw4 = calc_border_gap_half_width(self.border_width, c)
                     with gc:
                         gc.set_line_width(self.border_width + 1)
                         if isinstance(c, (BorderLine, Tee, Elbow, Cross)):
@@ -201,7 +206,7 @@ def angle(x, y):
             gc.set_stroke_color(self._convert_color(self.default_color))
             for t, c in self.connections:
                 if isinstance(c, BorderLine):
-                    dw = math.atan((c.width - c.border_width / 2) / r)
+                    dw = math.atan(calc_border_gap_half_width(self.border_width, c) / r)
 
                     p1, p2 = c.start_point, c.end_point
                     p2x, p2y = p2.get_xy()