extraction_line: add pre-actuation preview and structured confirmations

New ActuationPreview dataclass with fields:
- requested_action, allowed, reasons_blocking, owner
- interlocks, affected_children, state_changes
- network_region_changes, requires_confirmation, warning_level

Manager API:
- preview_open_valve(name) -> ActuationPreview
- preview_close_valve(name) -> ActuationPreview
- Reuses existing _check_ownership, _check_soft_interlocks,
  _check_positive_interlocks logic

Canvas click flow:
- Click valve -> ask manager for preview
- Show structured dialog with current state, owner, interlocks,
  affected children, region volume changes
- Blocked actions show error dialog instead of silently failing
- Existing ManualSwitch/RoughValve confirmation preserved

SwitchManager:
- Add get_children() helper for preview child enumeration

Author: jirhiker

pychron/canvas/canvas2D/extraction_line_canvas2D.py

@@ -332,6 +332,116 @@ def set_state(state):
 
         event.handled = True
 
+        item = self.active_item
+        if item is None:
+            return
+
+        if self.manager and isinstance(item, (BaseValve, Switch)):
+            self.manager.set_selected_explanation_item(item)
+
+        if self.edit_mode:
+            if event.shift_down:
+                self._toggle_item_selection(item)
+                return
+
+            self.event_state = "drag"
+            event.window.set_pointer(self.drag_pointer)
+            return
+
+        if isinstance(item, Laser):
+            self._toggle_laser_state(item)
+            return
+
+        state = item.state
+        nstate = not state
+        if isinstance(item, Switch):
+            set_state(nstate)
+
+        else:
+            if not isinstance(item, BaseValve):
+                return
+
+            if item.soft_lock:
+                return
+
+            # Use preview API for structured confirmation
+            if self.manager and self.confirm_open:
+                action = "open" if nstate else "close"
+                preview_func = (
+                    self.manager.preview_open_valve if nstate else self.manager.preview_close_valve
+                )
+                preview = preview_func(item.name)
+
+                if not preview.allowed:
+                    self._show_preview_dialog(preview)
+                    return
+
+                if preview.requires_confirmation or self.confirm_open:
+                    if not self._show_preview_dialog(preview):
+                        return
+
+            ok, change = set_state(nstate)
+
+        if ok:
+            item.state = nstate
+
+        if change and ok:
+            self._select_hook(item)
+
+        if change:
+            self.invalidate_and_redraw()
+
+        event.handled = True
+
+    def _show_preview_dialog(self, preview):
+        """Show structured preview dialog. Returns True if user confirms."""
+        from pyface.api import confirm, YES
+
+        lines = []
+        action_label = "Open" if preview.requested_action == "open" else "Close"
+        lines.append("{} valve {}?".format(action_label, preview.valve_name))
+        lines.append("")
+
+        if preview.current_state is not None:
+            lines.append("Current state: {}".format("Open" if preview.current_state else "Closed"))
+
+        if preview.owner:
+            lines.append("Owner: {}".format(preview.owner))
+
+        if preview.is_soft_locked:
+            lines.append("WARNING: Software locked")
+
+        if preview.interlocks:
+            lines.append("Interlock present: {}".format(", ".join(preview.interlocks)))
+
+        if preview.affected_children:
+            lines.append("Also affects: {}".format(", ".join(preview.affected_children)))
+
+        if preview.network_region_changes:
+            for change in preview.network_region_changes:
+                lines.append(change)
+
+        if preview.reasons_blocking:
+            lines.append("")
+            lines.append("Blocked: {}".format("; ".join(preview.reasons_blocking)))
+
+        msg = "\n".join(lines)
+
+        if preview.warning_level == "error":
+            title = "Actuation Blocked"
+            from pyface.message_dialog import error
+
+            error(None, msg, title=title)
+            return False
+
+        if preview.warning_level == "warning":
+            title = "Actuation Warning"
+        else:
+            title = "Confirm Valve Action"
+
+        result = confirm(None, msg, title=title)
+        return result == YES
+
         item = self.active_item
         if item is None:
             return

pychron/extraction_line/actuation_preview.py

@@ -0,0 +1,50 @@
+# ===============================================================================
+# Copyright 2026 Jake Ross
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ===============================================================================
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class ActuationPreview:
+    """Preview of what would happen if a valve actuation is executed."""
+
+    requested_action: str  # "open" or "close"
+    valve_name: str
+    allowed: bool = True
+    reasons_blocking: List[str] = field(default_factory=list)
+    owner: Optional[str] = None
+    interlocks: List[str] = field(default_factory=list)
+    affected_children: List[str] = field(default_factory=list)
+    state_changes: List[str] = field(default_factory=list)
+    network_region_changes: List[str] = field(default_factory=list)
+    requires_confirmation: bool = False
+    warning_level: str = "none"  # "none", "info", "warning", "error"
+    is_soft_locked: bool = False
+    is_enabled: bool = True
+    current_state: Optional[bool] = None
+
+    @property
+    def summary(self) -> str:
+        if not self.allowed:
+            return "Blocked: {}".format("; ".join(self.reasons_blocking))
+        parts = []
+        if self.interlocks:
+            parts.append("Interlocks: {}".format(", ".join(self.interlocks)))
+        if self.affected_children:
+            parts.append("Affects: {}".format(", ".join(self.affected_children)))
+        if self.network_region_changes:
+            parts.append("Region changes: {}".format(", ".join(self.network_region_changes)))
+        return " | ".join(parts) if parts else "No side effects"

pychron/extraction_line/extraction_line_manager.py

@@ -45,6 +45,7 @@
 from pychron.core.wait.wait_group import WaitGroup
 from pychron.envisage.consoleable import Consoleable
 from pychron.extraction_line import LOG_LEVEL_NAMES, LOG_LEVELS
+from pychron.extraction_line.actuation_preview import ActuationPreview
 from pychron.extraction_line.canvas.state import (
     CanvasSystemState,
     NetworkSnapshot,
@@ -654,6 +655,135 @@ def open_valve(self, name, **kw):
     def close_valve(self, name, **kw):
         return self._open_close_valve(name, "close", **kw)
 
+    def preview_open_valve(self, name, description=None, address=None, sender_address=None):
+        """Dry-run preview of opening a valve. Returns ActuationPreview."""
+        return self._preview_actuation(name, "open", description, address, sender_address)
+
+    def preview_close_valve(self, name, description=None, address=None, sender_address=None):
+        """Dry-run preview of closing a valve. Returns ActuationPreview."""
+        return self._preview_actuation(name, "close", description, address, sender_address)
+
+    def _preview_actuation(self, name, action, description=None, address=None, sender_address=None):
+        """Build an ActuationPreview without executing the actuation."""
+        vm = self.switch_manager
+        preview = ActuationPreview(
+            requested_action=action,
+            valve_name=name,
+            current_state=None,
+        )
+
+        if vm is None:
+            preview.allowed = False
+            preview.reasons_blocking.append("Switch manager not available")
+            preview.warning_level = "error"
+            return preview
+
+        resolved = self._resolve_switch_name(name, description=description, address=address)
+        if not resolved:
+            preview.allowed = False
+            preview.reasons_blocking.append("Valve '{}' not found".format(name))
+            preview.warning_level = "error"
+            return preview
+
+        preview.valve_name = resolved
+        valve = vm.get_switch_by_name(resolved)
+        if valve is None:
+            preview.allowed = False
+            preview.reasons_blocking.append("Valve '{}' not found".format(resolved))
+            preview.warning_level = "error"
+            return preview
+
+        preview.current_state = valve.state
+        preview.is_soft_locked = valve.software_lock
+        preview.is_enabled = getattr(valve, "enabled", True)
+        preview.owner = valve.owner or ""
+
+        # Check if already in target state
+        target_state = action == "open"
+        if valve.state == target_state:
+            preview.allowed = False
+            preview.reasons_blocking.append(
+                "Valve is already {}".format("open" if target_state else "closed")
+            )
+            preview.warning_level = "info"
+            return preview
+
+        # Check soft lock
+        if valve.software_lock:
+            preview.allowed = False
+            preview.reasons_blocking.append("Software locked")
+            preview.warning_level = "warning"
+            return preview
+
+        # Check enabled
+        if not getattr(valve, "enabled", True):
+            preview.allowed = False
+            preview.reasons_blocking.append("Valve not enabled")
+            preview.warning_level = "warning"
+            return preview
+
+        # Check ownership
+        if not self._check_ownership(resolved, sender_address):
+            preview.allowed = False
+            preview.reasons_blocking.append("Owned by {}".format(valve.owner))
+            preview.warning_level = "warning"
+            return preview
+
+        # Check soft interlocks
+        if action == "open":
+            interlocked = vm._check_soft_interlocks(resolved)
+            if interlocked:
+                preview.allowed = False
+                preview.reasons_blocking.append("Interlock: {} is open".format(interlocked.name))
+                preview.warning_level = "error"
+                return preview
+
+            positive = vm._check_positive_interlocks(resolved)
+            if positive:
+                preview.allowed = False
+                preview.interlocks = positive
+                preview.reasons_blocking.append(
+                    "Positive interlocks not enabled: {}".format(", ".join(positive))
+                )
+                preview.warning_level = "warning"
+                return preview
+        else:
+            interlocked = vm._check_soft_interlocks(resolved)
+            if interlocked:
+                preview.allowed = False
+                preview.reasons_blocking.append("Interlock: {} is open".format(interlocked.name))
+                preview.warning_level = "error"
+                return preview
+
+        # Collect affected children
+        children = vm.get_children(resolved)
+        if children:
+            preview.affected_children = [c.name for c in children]
+
+        # Network region changes
+        if self.use_network and self.network:
+            try:
+                snapshot = self.network.compute_state()
+                if snapshot and resolved in snapshot.valves:
+                    nv = snapshot.valves[resolved]
+                    if nv.side_volumes:
+                        preview.network_region_changes = [
+                            "Volume changes from {:0.1f} to {:0.1f} cc".format(
+                                min(nv.side_volumes), max(nv.side_volumes) + nv.valve_volume
+                            )
+                        ]
+                    if nv.region_id:
+                        preview.network_region_changes.append("Region: {}".format(nv.region_id))
+            except BaseException:
+                pass
+
+        # Determine if confirmation is needed
+        if preview.affected_children or preview.network_region_changes:
+            preview.requires_confirmation = True
+            preview.warning_level = "info"
+
+        return preview
+
     def sample(self, name, **kw):
         def sample():
             valve = self.switch_manager.get_switch_by_name(name)