chartflow 0.1__py3-none-any.whl

chartflow/flow/qchart.py

@@ -0,0 +1,1250 @@
+from __future__ import annotations
+"""
+qflow.qchart - PyQt6 widget for visualizing qfsm Stage/Logic state machines
+
+This module provides QFlowChart, a reusable widget that visualizes qfsm state
+machines with interactive execution controls.
+
+Example:
+    from chartflow.flow.qchart import QFlowChart
+    from chartflow.fsm import Logic
+    from PyQt6.QtWidgets import QApplication
+
+    class MyLogic(Logic):
+        NAME = "MyLogic"
+
+        def start(self, inst):
+            return "running"
+
+        def running(self, inst):
+            return None  # Stay in this state
+
+    app = QApplication([])
+    logic = MyLogic()
+    chart = QFlowChart(logic=logic)
+    chart.show()
+    app.exec()
+"""
+
+import re
+import sys
+from PyQt6.QtCore import QTime
+
+
+
+from typing import Any, Optional
+
+from PyQt6.QtWidgets import (
+    QWidget, QVBoxLayout, QHBoxLayout,
+    QPushButton, QLabel, QDialog, QTabWidget,
+    QTextEdit, QSplitter, QApplication
+)
+from PyQt6.QtCore import Qt, QPointF, pyqtSignal, QObject, QTimer, QVariantAnimation, QEasingCurve
+from PyQt6.QtGui import QColor, QFont
+
+from chartflow.fsm.stage import Stage
+from chartflow.fsm.scheduler import Scheduler
+from chartflow.fsm.utils import GetES
+from chartflow.node.node_canvas import QNodeCanvas
+from chartflow.node.enums import NodeShape, ConnectionType
+from chartflow.node.layout_utils import DenseLayoutEngine, ViewportFitter
+from chartflow.theme import PALETTE
+
+from .editor import StageEditor, StageEditorDialog
+from .chart import Chart, ChartNode, ChartEdge, ChartLogic
+
+# Module-level QApplication reference to prevent garbage collection
+_qapp: QApplication | None = None
+
+
+class NodeDetailDialog(QDialog):
+    """
+    Dialog to display and edit node documentation and source code.
+
+    Uses StageEditor for code editing with syntax highlighting,
+    code completion, and context-aware analysis.
+    """
+
+    def __init__(
+        self,
+        node_name: str,
+        doc: str,
+        code: str,
+        stage_class: type[Stage] | None = None,
+        parent: QWidget | None = None
+    ) -> None:
+        super().__init__(parent)
+        self._nodename = node_name
+        self._doc = doc
+        self._code = code
+        self._stage_class = stage_class
+        self._setupUi()
+
+    def _setupUi(self) -> None:
+        self.setWindowTitle(f"Node: {self._nodename}")
+        self.setGeometry(100, 100, 1000, 750)
+        self.setStyleSheet(f"""
+            QDialog {{
+                background-color: {PALETTE.window};
+            }}
+        """)
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(10, 10, 10, 10)
+        layout.setSpacing(10)
+
+        # Check if we can use StageEditor (need stage_class)
+        if self._stage_class is not None:
+            self._setup_editor_view(layout)
+        else:
+            self._setup_simple_view(layout)
+
+    def _setup_editor_view(self, layout: QVBoxLayout) -> None:
+        """Setup view with StageEditor for editing."""
+        # Doc header
+        if self._doc:
+            doc_label = QLabel(f"Documentation: {self._doc}")
+            doc_label.setStyleSheet(f"""
+                QLabel {{
+                    color: {PALETTE.text_dim};
+                    font-size: 12px;
+                    padding: 6px 8px;
+                    background-color: {PALETTE.panel};
+                    border: 1px solid {PALETTE.border};
+                    border-radius: 4px;
+                }}
+            """)
+            doc_label.setWordWrap(True)
+            layout.addWidget(doc_label)
+
+        # StageEditor for code editing
+        self._editor = StageEditor()
+        self._editor.set_stage_context(self._stage_class, self._nodename)
+
+        if self._code:
+            self._editor.set_code(self._code)
+
+        layout.addWidget(self._editor, stretch=1)
+
+        # Buttons
+        btn_layout = QHBoxLayout()
+        btn_layout.addStretch()
+
+        self._btn_close = QPushButton("Close")
+        self._btn_close.setObjectName("primary")
+        self._btn_close.setCursor(Qt.CursorShape.PointingHandCursor)
+        self._btn_close.clicked.connect(self.accept)
+        btn_layout.addWidget(self._btn_close)
+
+        layout.addLayout(btn_layout)
+
+    def _setup_simple_view(self, layout: QVBoxLayout) -> None:
+        """Setup simple read-only view when stage_class is not available."""
+        # Tab widget
+        tabs = QTabWidget()
+        layout.addWidget(tabs)
+
+        # Doc tab
+        doc_edit = QTextEdit()
+        doc_edit.setReadOnly(True)
+        doc_edit.setPlainText(self._doc if self._doc else "No documentation available.")
+        doc_edit.setStyleSheet(self._textStyle())
+        tabs.addTab(doc_edit, "Documentation")
+
+        # Code tab
+        code_edit = QTextEdit()
+        code_edit.setReadOnly(True)
+        code_edit.setPlainText(self._code if self._code else "No source code available.")
+        code_edit.setStyleSheet(self._textStyle())
+        tabs.addTab(code_edit, "Source Code")
+
+        # Close button
+        btn_layout = QHBoxLayout()
+        btn_layout.addStretch()
+        btn_close = QPushButton("Close")
+        btn_close.setObjectName("primary")
+        btn_close.setCursor(Qt.CursorShape.PointingHandCursor)
+        btn_close.clicked.connect(self.accept)
+        btn_layout.addWidget(btn_close)
+        layout.addLayout(btn_layout)
+
+    def _textStyle(self) -> str:
+        return f"""
+            QTextEdit {{
+                background-color: {PALETTE.code_bg};
+                color: {PALETTE.code_text};
+                border: 1px solid {PALETTE.border};
+                border-radius: 9px;
+                font-family: 'JetBrains Mono', 'IBM Plex Mono', 'Consolas', monospace;
+                font-size: 12.5px;
+                padding: 11px 14px;
+            }}
+            QTextEdit QScrollBar:vertical {{
+                background-color: {PALETTE.code_bg};
+                width: 9px;
+            }}
+            QTextEdit QScrollBar::handle:vertical {{
+                background-color: #2A3B52;
+                border-radius: 8px;
+                min-height: 20px;
+            }}
+        """
+
+
+class _EventBridge(QObject):
+    """Bridge to marshal events from any thread to main thread via Qt signals."""
+    stateChanged = pyqtSignal(dict)
+
+    def __init__(self, handler: callable) -> None:
+        super().__init__()
+        self._handler = handler
+        self.stateChanged.connect(self._onStateChanged)
+
+    def _onStateChanged(self, data: dict) -> None:
+        self._handler(data)
+
+    def onEvent(self, data: dict) -> None:
+        """Called from any thread - emits signal to main thread."""
+        self.stateChanged.emit(data)
+
+
+class QFlowChart(QWidget):
+    """
+    PyQt6 widget for visualizing and interacting with qfsm state machines.
+
+    Features:
+    - Visual node graph display (auto-generated from Stage/Logic states)
+    - Step-by-step execution with manual control
+    - Auto-execution mode
+    - State highlighting and transitions
+    - Thread-safe event handling
+
+    Attributes:
+        stage: The Stage/Logic instance being visualized
+        scheduler: The Scheduler singleton instance
+
+    Example:
+        # Simple usage with default controls
+        logic = MyLogic()
+        chart = QFlowChart(logic=logic)
+        chart.show()
+
+        # Custom control (no built-in buttons)
+        chart = QFlowChart(logic=logic, show_controls=False)
+        chart.doStep()  # Manual step
+    """
+
+    # Default colors
+    # 卡片底色沿用 uipcweb 白底；执行中(start)节点保持之前的亮绿色
+    COLOR_DEFAULT = "#FFFFFF"
+    COLOR_BORDER = "#D6D9DF"
+    COLOR_ACTIVE = "#4CAF50"
+    COLOR_ACTIVE_BORDER = "#2E7D32"
+    COLOR_FINISHED = "#FF6B6B"
+
+    def __init__(
+        self,
+        stage: Stage | None = None,
+        show_controls: bool = True,
+        parent: QWidget | None = None
+    ) -> None:
+        """
+        Initialize QFlowChart.
+
+        Args:
+            stage: Stage/Logic instance to visualize (can be set later via setStage)
+            show_controls: Whether to show control buttons (step)
+            parent: Parent widget
+        """
+        # Ensure QApplication exists (for headless/test environments)
+        global _qapp
+        if QApplication.instance() is None:
+            _qapp = QApplication(sys.argv)
+
+        # Apply the chartflow dark theme if the app has no stylesheet yet.
+        from chartflow.theme import applyTheme
+        _app = QApplication.instance()
+        if _app is not None and not _app.styleSheet():
+            applyTheme(_app)
+
+        super().__init__(parent)
+
+        # Core components
+        self._stage: Stage | None = None
+        self._scheduler: Scheduler = Scheduler()
+        self._event_bridge: _EventBridge | None = None
+
+        # Chart data model (for IChart interface compatibility)
+        self._chart = Chart()
+
+        # Node mapping: state_name -> NodeItem
+        self._nodemap: dict[str, Any] = {}
+        self._current_node: Any | None = None
+
+        # Animation tracking
+        self._fade_timer: QTimer | None = None
+        self._fade_animations: list = []
+
+        # UI options
+        self._show_controls = show_controls
+
+        # Layout pending flag (for deferred layout when viewport not ready)
+        self._layout_pending = False
+
+        # Setup UI
+        self._setupUi()
+
+        # Set stage if provided
+        if stage is not None:
+            self.setStage(stage)
+            
+
+    def _setupUi(self) -> None:
+        """Setup the user interface."""
+        # Main horizontal layout: left (canvas + controls) | right (event log)
+        self._main_layout = QHBoxLayout(self)
+        self._main_layout.setContentsMargins(10, 10, 10, 10)
+        self._main_layout.setSpacing(10)
+
+        # Left side: vertical layout with canvas and controls
+        self._left_layout = QVBoxLayout()
+        self._left_layout.setSpacing(10)
+
+        # Node Canvas
+        self._canvas = QNodeCanvas(self)
+        self._left_layout.addWidget(self._canvas, stretch=1)
+
+        # Control panel
+        self._ctrl_layout = QHBoxLayout()
+        self._ctrl_layout.setSpacing(10)
+
+        # Info label
+        self._infolbl = QLabel("State: - | Now: 0")
+        self._infolbl.setStyleSheet(f"""
+            QLabel {{
+                background-color: {PALETTE.input};
+                color: {PALETTE.success};
+                padding: 8px 15px;
+                border: 1px solid {PALETTE.border};
+                border-radius: 4px;
+                font-family: Consolas, Monaco, monospace;
+                font-size: 12px;
+                font-weight: bold;
+            }}
+        """)
+        self._ctrl_layout.addWidget(self._infolbl)
+        self._ctrl_layout.addStretch()
+
+        # Control buttons
+        if self._show_controls:
+            self._btn_step = QPushButton("Next Step")
+            self._btn_step.setToolTip("Execute one step")
+            self._btn_step.clicked.connect(self.doStep)
+            self._btn_step.setObjectName("primary")
+            self._btn_step.setCursor(Qt.CursorShape.PointingHandCursor)
+            self._ctrl_layout.addWidget(self._btn_step)
+
+        self._left_layout.addLayout(self._ctrl_layout)
+        self._main_layout.addLayout(self._left_layout, stretch=3)
+
+        # Right side: event log
+        self._event_log = QTextEdit()
+        self._event_log.setReadOnly(True)
+        self._event_log.setMaximumWidth(300)
+        self._event_log.setStyleSheet(f"""
+            QTextEdit {{
+                background-color: {PALETTE.code_bg};
+                color: {PALETTE.code_text};
+                border: 1px solid {PALETTE.border};
+                border-radius: 9px;
+                font-family: "JetBrains Mono", "IBM Plex Mono", Consolas, monospace;
+                font-size: 11.5px;
+                padding: 9px 12px;
+            }}
+            QTextEdit QScrollBar:vertical {{
+                background-color: {PALETTE.code_bg};
+                width: 9px;
+            }}
+            QTextEdit QScrollBar::handle:vertical {{
+                background-color: #2A3B52;
+                border-radius: 8px;
+                min-height: 20px;
+            }}
+        """)
+        self._event_log.setPlaceholderText("Event log...")
+        self._main_layout.addWidget(self._event_log, stretch=1)
+
+        # Button cooldown timer
+        self._btn_cooldown_timer: QTimer | None = None
+
+    @property
+    def stage(self) -> Stage | None:
+        """Get the current Stage/Logic instance."""
+        return self._stage
+
+    @property
+    def scheduler(self) -> Scheduler:
+        """Get the scheduler instance."""
+        return self._scheduler
+
+    def setStage(self, stage: Stage) -> None:
+        """
+        Set or change the Stage/Logic instance to visualize.
+
+        Args:
+            stage: Stage/Logic instance to visualize
+        """
+        # Cleanup previous
+        self._cleanup()
+
+        self._stage = stage
+
+        # Build node graph from stage states
+        self._buildGraph()
+
+        # Setup event bridges for async updates
+        self._event_bridge = _EventBridge(self._onStateChanged)
+        stage.listenFor("changed", self._event_bridge.onEvent)
+
+        self._enter_bridge = _EventBridge(self._onStateEnter)
+        stage.listenFor("enter", self._enter_bridge.onEvent)
+
+        self._behavior_bridge = _EventBridge(self._onCompleted)
+        stage.listenFor("behavior_completed", self._behavior_bridge.onEvent)
+
+        self._compisited_bridge = _EventBridge(self._onCompisited)
+        stage.listenFor("compisited", self._compisited_bridge.onEvent)
+
+        # Initial highlight and info update
+        current = stage.current
+        self._highlightNode(current or "-")
+        self._updateInfo(current)
+
+        self._updateButtons()
+        
+
+    def _buildGraph(self) -> None:
+        """Build node graph from stage states with auto-layout."""
+        self._canvas.clear()
+        self._nodemap.clear()
+        self._current_node = None
+
+        if self._stage is None:
+            return
+
+        states = self._stage.states
+        if not states:
+            return
+
+        # Create nodes at origin first (layout engine will position them)
+        # 获取 Stage 类的装饰器信息
+        stage_class = self._stage.__class__
+        recursive_states = getattr(stage_class, "__recursive__", set())
+        behaviors = getattr(stage_class, "__behaviors__", {})
+
+        for state in states:
+            shape = self._getShapeForState(state)
+            node = self._canvas.addNode(state, QPointF(0, 0), shape)
+            self._nodemap[state] = node
+
+            # 设置 recursive 装饰器
+            if state in recursive_states:
+                node.decorator = "recursive"
+            # 设置 behavior/sequence/selector/parallel 装饰器
+            elif state in behaviors:
+                behavior = behaviors[state]
+                composite = behavior.get("composite")
+                if composite in ("sequence", "selector", "parallel"):
+                    node.decorator = composite
+                else:
+                    node.decorator = "behavior"
+
+            # Connect node edit request to show details
+            node.editRequested.connect(self._onNodeEditRequested)
+
+        # Create edges between states
+        self._createEdges(states)
+
+        # Apply auto layout and fit viewport
+        self._doAutoLayout()
+
+    def _doAutoLayout(self) -> None:
+        """Apply auto-layout and fit viewport to show all nodes."""
+        if not self._nodemap:
+            return
+
+        # Check if viewport is ready (has valid size)
+        viewport = self._canvas.viewport()
+        if viewport.width() <= 0 or viewport.height() <= 0:
+            # Viewport not ready, defer layout
+            self._layout_pending = True
+            return
+
+        self._layout_pending = False
+        node_count = len(self._nodemap)
+
+        if node_count == 1:
+            # Single node: just center it
+            ViewportFitter(self._canvas).centerOnNodes()
+        elif node_count > 1:
+            # Multiple nodes: apply hierarchical layout
+            engine = DenseLayoutEngine(self._canvas)
+            engine.autoLayout("hierarchical")
+            # Fit viewport with margin to show all nodes
+            ViewportFitter(self._canvas).fitViewport(margin=50)
+
+        # Force update
+        self._canvas.viewport().update()
+
+    def relayout(self) -> None:
+        """
+        Re-apply auto-layout to current graph.
+
+        Call this after manual node movement or when the graph needs reorganization.
+        """
+        self._doAutoLayout()
+
+    def _fitViewport(self) -> None:
+        """Fit viewport to show all nodes without recalculating layout."""
+        if not self._nodemap:
+            return
+
+        viewport = self._canvas.viewport()
+        if viewport.width() <= 0 or viewport.height() <= 0:
+            return
+
+        node_count = len(self._nodemap)
+        if node_count == 1:
+            ViewportFitter(self._canvas).centerOnNodes()
+        else:
+            ViewportFitter(self._canvas).fitViewport(margin=50)
+
+        self._canvas.viewport().update()
+
+    def showEvent(self, event) -> None:
+        """Handle widget show event - perform deferred layout if needed."""
+        super().showEvent(event)
+
+        # If layout was deferred due to viewport not being ready, do it now
+        if self._layout_pending and self._nodemap:
+            # Use single shot timer to ensure viewport has correct size
+            QTimer.singleShot(0, self._doAutoLayout)
+
+    def resizeEvent(self, event) -> None:
+        """Handle resize event - re-fit viewport to new size."""
+        super().resizeEvent(event)
+
+        # Only refit if we have nodes and layout is not pending
+        if self._nodemap and not self._layout_pending:
+            # Use timer to avoid excessive refitting during resize
+            QTimer.singleShot(100, self._fitViewport)
+
+    def _getShapeForState(self, state: str) -> NodeShape:
+        """Determine node shape based on state name."""
+        lower = state.lower()
+        if "entry" in lower or lower == "start":
+            return NodeShape.ELLIPSE
+        if "exit" in lower or lower == "end" or lower == "stop":
+            return NodeShape.ELLIPSE
+        if "decision" in lower or "check" in lower or "if" in lower:
+            return NodeShape.DIAMOND
+        return NodeShape.RECTANGLE
+
+    def _createEdges(self, states: list[str]) -> None:
+        """
+        Create edges between states based on possible transitions.
+
+        Edge types:
+        - Behavior tree parent -> child (structural relationship)
+        - Regular state -> return target (execution flow)
+        """
+
+        if self._stage is None:
+            return
+
+        # Get behavior tree info
+        stage_class = self._stage.__class__
+        behaviors = getattr(stage_class, "__behaviors__", {})
+
+        # Get node info with source code
+        try:
+            nodes_info = self._stage.extractNodes()
+        except Exception:
+            nodes_info = {}
+
+        # Pattern to match return "state_name" or return 'state_name'
+        return_pattern = re.compile(r'return\s+["\']([a-zA-Z_][a-zA-Z0-9_]*)["\']')
+
+        # First: Create behavior tree structural edges
+        for state in states:
+            if state not in self._nodemap:
+                continue
+
+            if state in behaviors:
+                behavior = behaviors[state]
+                children = behavior.get("children", [])
+                composite = behavior.get("composite")
+
+                # Normalize children to list
+                if isinstance(children, str):
+                    children = [children]
+                elif not children:
+                    children = []
+
+                # Create edges based on behavior type
+                if composite in ("sequence", "selector", "parallel"):
+                    # Composite: connect parent to all children (structural)
+                    for child in children:
+                        if child in self._nodemap and child != state:
+                            self._canvas.addConnection(
+                                self._nodemap[state],
+                                self._nodemap[child],
+                                connection_type=ConnectionType.BEZIER
+                            )
+                else:
+                    # Simple behavior: single child transition
+                    for child in children:
+                        if child in self._nodemap and child != state:
+                            self._canvas.addConnection(
+                                self._nodemap[state],
+                                self._nodemap[child],
+                                connection_type=ConnectionType.BEZIER
+                            )
+
+        # Second: Create regular state transition edges from return statements
+        for state in states:
+            if state not in self._nodemap:
+                continue
+
+            # Skip behavior tree nodes - their children are handled above
+            if state in behaviors:
+                continue
+
+            # Regular state: parse return statements
+            info = nodes_info.get(state, {})
+            code = info.get("code", "")
+            targets = return_pattern.findall(code)
+
+            for target in targets:
+                if target in self._nodemap and target != state:
+                    self._canvas.addConnection(
+                        self._nodemap[state],
+                        self._nodemap[target],
+                        connection_type=ConnectionType.BEZIER
+                    )
+
+    def _highlightNode(self, state: str) -> None:
+        """Highlight the current active node."""
+        # Reset previous: clear highlight and single marker
+        if self._current_node is not None:
+            self._current_node.setColor(QColor(self.COLOR_DEFAULT))
+            self._current_node.setBorder(2, QColor(self.COLOR_BORDER))
+            self._current_node.setSingleMarkerVisible(False)
+
+        # Highlight new
+        if state in self._nodemap:
+            node = self._nodemap[state]
+            node.setColor(QColor(self.COLOR_ACTIVE))
+            node.setBorder(2, QColor(self.COLOR_ACTIVE_BORDER))
+            self._current_node = node
+
+        self._canvas.viewport().update()
+
+    def _updateInfo(self, state: str | None = None) -> None:
+        """Update the info label."""
+        if state is None:
+            state = self._stage.current if self._stage else "-"
+        now = self._stage.now if self._stage else 0
+        self._infolbl.setText(f"State: {state} | Now: {now}")
+
+    def _isFinished(self) -> bool:
+        """Check if execution has finished."""
+        if self._stage is None:
+            return True
+        # Check for Logic instances
+        if hasattr(self._stage, "alive"):
+            return not self._stage.alive
+        # Check if current state is exit-like
+        if self._stage.current in ("exit", "end", "stop", None):
+            return True
+        return False
+
+    def _updateButtons(self) -> None:
+        """Update button states."""
+        if not self._show_controls:
+            return
+        self._btn_step.setEnabled(not self._isFinished())
+
+    def doStep(self) -> None:
+        """
+        Execute one step of the state machine.
+
+        Pushes 'system_next' event to trigger scheduler tick (non-blocking).
+        Safe to call from UI thread.
+        """
+        if self._isFinished():
+            return
+
+        # Double-check alive status before lighting up marker
+        if hasattr(self._stage, "alive") and not self._stage.alive:
+            return
+
+        # Light up single marker on current node (execution starting)
+        current = self._stage.current if self._stage else None
+        if current and current in self._nodemap:
+            self._nodemap[current].setSingleMarkerVisible(True)
+
+        self._scheduler.pushEvent("system_next", {})
+
+    def doRun(self, ticks: int = 1) -> None:
+        """
+        Execute multiple steps (non-blocking via events).
+
+        Args:
+            ticks: Number of ticks to execute
+        """
+        for _ in range(ticks):
+            if self._isFinished():
+                break
+            self.doStep()
+
+    def _logEvent(self, event_type: str, details: str) -> None:
+        """Log an event to the event log panel with colored event types."""
+        if hasattr(self, '_event_log') and self._event_log:
+            time_str = QTime.currentTime().toString("hh:mm:ss.zzz")
+
+            # Color mapping for event types (tuned for the dark event-log bg)
+            color_map = {
+                "ENTER": "#4FC1FF",      # light blue
+                "COMPISITED": "#FFA940", # orange (accent)
+                "CHANGED": "#7ee787",    # light green
+                "COMPLETED": "#C792EA",  # light purple
+            }
+            color = color_map.get(event_type, PALETTE.code_text)
+
+            # Use HTML for colored event type (light text on dark log)
+            html = (f"<span style='color:{PALETTE.code_dim}'>[{time_str}]</span> "
+                    f"<span style='color:{color};font-weight:bold'>{event_type}</span>: "
+                    f"<span style='color:{PALETTE.code_text}'>{details}</span>")
+            self._event_log.append(html)
+
+            # Auto-scroll to bottom
+            scrollbar = self._event_log.verticalScrollBar()
+            scrollbar.setValue(scrollbar.maximum())
+
+    def _onStateEnter(self, data: dict) -> None:
+        """Handle state enter event from event system.
+
+        This is called before a state executes, allowing the UI to show
+        which state is about to run.
+        """
+        state_name = data.get("state")
+        self._logEvent("ENTER", state_name or "-")
+
+        if state_name and state_name in self._nodemap:
+            # Clear ALL nodes' marker and green highlight (insurance cleanup)
+            for node in self._nodemap.values():
+                node.setSingleMarkerVisible(False)
+                node.setColor(QColor(self.COLOR_DEFAULT))
+                node.setBorder(2, QColor(self.COLOR_BORDER))
+
+            node = self._nodemap[state_name]
+            # Add lightning marker and green highlight
+            node.setSingleMarkerVisible(True)
+            node.setColor(QColor(self.COLOR_ACTIVE))
+            node.setBorder(2, QColor(self.COLOR_ACTIVE_BORDER))
+            self._current_node = node
+            self._updateInfo(state_name)
+
+    def _onStateChanged(self, data: dict) -> None:
+        """Handle state change event from event system.
+
+        Logic:
+        - If old != new: remove old's marker and highlight, highlight new (green)
+        - If old == new: only remove marker
+        """
+        to_state = data.get("new")
+        from_state = data.get("old")
+        event_type = data.get("type", "-")
+        result = data.get("result")
+
+        self._logEvent("CHANGED", f"{from_state} -> {to_state} ({event_type}, result={result})")
+
+        if not to_state:
+            return
+
+        # For behavior events: from_state is the node that just FINISHED executing
+        # Should clear its marker, then highlight the new state
+        if event_type == "behavior":
+            # Clear lightning from the state that just finished executing
+            if from_state and from_state in self._nodemap:
+                self._nodemap[from_state].setSingleMarkerVisible(False)
+            # Continue to highlight the new state (to_state)
+
+        # For regular state transitions: from_state -> to_state
+        if from_state and from_state in self._nodemap:
+            old_node = self._nodemap[from_state]
+            # Always remove lightning marker from old state
+            old_node.setSingleMarkerVisible(False)
+
+            if from_state != to_state:
+                # old != new: also remove highlight (green) from old state
+                old_node.setColor(QColor(self.COLOR_DEFAULT))
+                old_node.setBorder(2, QColor(self.COLOR_BORDER))
+
+        # Highlight new state (green)
+        if to_state in self._nodemap:
+            new_node = self._nodemap[to_state]
+            new_node.setColor(QColor(self.COLOR_ACTIVE))
+            new_node.setBorder(2, QColor(self.COLOR_ACTIVE_BORDER))
+            self._current_node = new_node
+
+        self._updateInfo(to_state)
+        self._updateButtons()
+
+        # Visual feedback for finished state
+        if to_state in ("exit", "end", "stop"):
+            self._infolbl.setStyleSheet(f"""
+                QLabel {{
+                    background-color: {PALETTE.input};
+                    color: {PALETTE.error};
+                    padding: 8px 15px;
+                    border: 1px solid {PALETTE.border};
+                    border-radius: 4px;
+                    font-family: Consolas, Monaco, monospace;
+                    font-size: 12px;
+                    font-weight: bold;
+                }}
+            """)
+
+    def _onCompisited(self, data: dict) -> None:
+        """
+        Handle compisited event from stage.
+
+        When a composite node exits:
+        - Composite node itself triggers gradient color effect
+        - Clear child node's color and marker (but not gradient effect)
+        """
+        composite_name = data.get("name")
+        child_name = data.get("child")
+        result = data.get("result")
+        self._logEvent("COMPISITED", f"{composite_name} (child={child_name}, result={result})")
+
+        # Composite node triggers gradient effect
+        if composite_name and composite_name in self._nodemap:
+            composite_node = self._nodemap[composite_name]
+            # Apply gradient based on result
+            self._applyNodeResult(composite_name, result)
+
+        # Clear child node's color and marker (insurance cleanup)
+        if child_name and child_name in self._nodemap:
+            child_node = self._nodemap[child_name]
+            # Remove lightning marker
+            child_node.setSingleMarkerVisible(False)
+            # Remove green highlight (but keep gradient if any)
+            # Only reset if it's the current node
+            if self._current_node and child_node == self._current_node:
+                child_node.setColor(QColor(self.COLOR_DEFAULT))
+                child_node.setBorder(2, QColor(self.COLOR_BORDER))
+                self._current_node = None
+
+    def _onCompleted(self, data: dict) -> None:
+        """
+        Handle behavior tree completion event.
+
+        Shows success/failure visualization:
+        - Success nodes: green for 1s, then fade out over 2s
+        - Failure nodes: red for 1s, then fade out over 2s
+        - Current node is excluded (stays green as active)
+        """
+        success = data.get("success", False)
+        history = data.get("history", [])
+        self._logEvent("COMPLETED", f"success={success}, history={len(history)} nodes")
+
+        # Colors
+        COLOR_SUCCESS = "#4CAF50"  # Green
+        COLOR_FAIL = "#F44336"     # Red
+
+        # Track nodes to animate
+        marked_nodes = []
+
+        for node_name, status in history:
+            if node_name not in self._nodemap:
+                continue
+
+            node = self._nodemap[node_name]
+            # success 和 break 都视为成功（绿色），其他（fail）视为失败（红色）
+            is_success = status in ("success", "break")
+            color = QColor(COLOR_SUCCESS) if is_success else QColor(COLOR_FAIL)
+
+            # Set color immediately
+            node.setColor(color)
+
+            # Skip current node for animation (it stays active)
+            if self._current_node and node == self._current_node:
+                continue
+
+            # Skip nodes with break status (they should stay green, not fade)
+            if status == "break":
+                continue
+
+            marked_nodes.append(node)
+
+        # Clear running marker from ALL nodes when behavior tree completes
+        # (execution stopped but marker might still be showing on any node)
+        for node in self._nodemap.values():
+            node.setSingleMarkerVisible(False)
+
+        # Clear any existing fade timer
+        if self._fade_timer is not None:
+            self._fade_timer.stop()
+            self._fade_timer.deleteLater()
+
+        for anim in self._fade_animations:
+            anim.stop()
+        self._fade_animations = []
+
+        # Create timer to start fade after 1s
+        self._fade_timer = QTimer(self)
+        self._fade_timer.setSingleShot(True)
+        self._fade_timer.timeout.connect(lambda: self._startFadeAnimation(marked_nodes))
+        self._fade_timer.start(300)  # 0.3 second delay
+
+    def _startFadeAnimation(self, nodes: list) -> None:
+        """Start fade out animation for marked nodes."""
+        self._fade_animations = []
+        COLOR_DEFAULT = self.COLOR_DEFAULT
+
+        for node in nodes:
+            # Get current color
+            current_color = node._custom_fill_color if hasattr(node, '_custom_fill_color') else QColor(COLOR_DEFAULT)
+
+            # Create QVariantAnimation (works with any object, not just QObject)
+            anim = QVariantAnimation()
+            anim.setDuration(700)  # 0.7 seconds fade
+            anim.setStartValue(current_color)
+            anim.setEndValue(QColor(COLOR_DEFAULT))
+            anim.setEasingCurve(QEasingCurve.Type.InOutQuad)
+
+            # Connect valueChanged to update node color
+            anim.valueChanged.connect(lambda color, n=node: n.setColor(color))
+
+            anim.start()
+            self._fade_animations.append(anim)
+
+        # After all animations finish, re-highlight current node to ensure it stays green
+        if self._fade_animations:
+            last_anim = self._fade_animations[-1]
+            last_anim.finished.connect(lambda: self._rehighlightCurrentNode())
+
+    def _applyNodeResult(self, node_name: str, result: Any) -> None:
+        """Apply immediate success/failure color to a node and fade it out.
+
+        This is called for behavior tree child nodes to show immediate feedback.
+        """
+        if node_name not in self._nodemap:
+            return
+
+        node = self._nodemap[node_name]
+
+        # Determine color based on result
+        COLOR_SUCCESS = "#4CAF50"
+        COLOR_FAIL = "#F44336"
+        COLOR_DEFAULT = self.COLOR_DEFAULT
+
+        if result is False:
+            color = QColor(COLOR_FAIL)
+        elif result is True or result is None:
+            color = QColor(COLOR_SUCCESS)
+        else:
+            # String or other result type - treat as success (transition)
+            color = QColor(COLOR_SUCCESS)
+
+        # Set color immediately
+        node.setColor(color)
+
+        # Skip animation if this is the current active node
+        if self._current_node and node == self._current_node:
+            return
+
+        # Create fade animation after a short delay
+        QTimer.singleShot(300, lambda: self._fadeNodeToDefault(node))
+
+    def _fadeNodeToDefault(self, node) -> None:
+        """Fade a single node back to default color."""
+        COLOR_DEFAULT = self.COLOR_DEFAULT
+
+        # Get current color
+        current_color = node._custom_fill_color if hasattr(node, '_custom_fill_color') else QColor(COLOR_DEFAULT)
+
+        # Create fade animation
+        anim = QVariantAnimation()
+        anim.setDuration(700)
+        anim.setStartValue(current_color)
+        anim.setEndValue(QColor(COLOR_DEFAULT))
+        anim.setEasingCurve(QEasingCurve.Type.InOutQuad)
+        anim.valueChanged.connect(lambda color, n=node: n.setColor(color))
+        anim.start()
+
+        # Track animation
+        if not hasattr(self, '_fade_animations'):
+            self._fade_animations = []
+        self._fade_animations.append(anim)
+
+        # Clean up finished animations
+        anim.finished.connect(lambda: self._fade_animations.remove(anim) if anim in self._fade_animations else None)
+
+    def _rehighlightCurrentNode(self) -> None:
+        """Re-highlight current node after animations complete."""
+        if self._current_node is not None:
+            self._current_node.setColor(QColor(self.COLOR_ACTIVE))
+            self._current_node.setBorder(2, QColor(self.COLOR_ACTIVE_BORDER))
+
+    def _onNodeEditRequested(self, node) -> None:
+        """Handle node edit request - show node details dialog with StageEditor."""
+        if self._stage is None:
+            return
+
+        node_name = node.name
+
+        # Extract node info from stage
+        try:
+            nodes_info = self._stage.extractNodes()
+            info = nodes_info.get(node_name, {})
+            doc = info.get("doc", "")
+            code = info.get("code", "")
+        except Exception:
+            doc = ""
+            code = ""
+
+        # Get stage class for context-aware editing
+        stage_class = self._stage.__class__
+
+        # Show detail dialog with StageEditor
+        dialog = NodeDetailDialog(node_name, doc, code, stage_class, self)
+        dialog.exec()
+
+    def _cleanup(self) -> None:
+        """Cleanup resources."""
+        # Cancel listener from current stage
+        if self._stage is not None and self._event_bridge is not None:
+            try:
+                self._stage.cancelListen("changed", self._event_bridge.onEvent)
+            except Exception:
+                pass
+
+        if self._stage is not None and hasattr(self, '_enter_bridge') and self._enter_bridge is not None:
+            try:
+                self._stage.cancelListen("enter", self._enter_bridge.onEvent)
+            except Exception:
+                pass
+
+        if self._stage is not None and hasattr(self, '_behavior_bridge') and self._behavior_bridge is not None:
+            try:
+                self._stage.cancelListen("behavior_completed", self._behavior_bridge.onEvent)
+            except Exception:
+                pass
+
+        if self._stage is not None and hasattr(self, '_compisited_bridge') and self._compisited_bridge is not None:
+            try:
+                self._stage.cancelListen("compisited", self._compisited_bridge.onEvent)
+            except Exception:
+                pass
+
+        # Delete event bridges
+        if self._event_bridge is not None:
+            self._event_bridge.deleteLater()
+            self._event_bridge = None
+
+        if hasattr(self, '_enter_bridge') and self._enter_bridge is not None:
+            self._enter_bridge.deleteLater()
+            self._enter_bridge = None
+
+        if hasattr(self, '_behavior_bridge') and self._behavior_bridge is not None:
+            self._behavior_bridge.deleteLater()
+            self._behavior_bridge = None
+
+        if hasattr(self, '_compisited_bridge') and self._compisited_bridge is not None:
+            self._compisited_bridge.deleteLater()
+            self._compisited_bridge = None
+
+        self._stage = None
+
+    def kill(self) -> None:
+        """
+        Kill the underlying Stage/Logic instance.
+
+        This marks the logic as not alive and triggers cleanup.
+        Safe to call multiple times.
+        """
+        if self._stage is not None and hasattr(self._stage, "kill"):
+            self._stage.kill()
+
+    def closeEvent(self, event) -> None:
+        """Handle widget close - automatically kills the stage."""
+        self.kill()
+        self._cleanup()
+        event.accept()
+
+    # -------------------------------------------------------------------------
+    # IChart Interface Methods (delegated to internal Chart instance)
+    # -------------------------------------------------------------------------
+
+    @property
+    def nodes(self) -> list[ChartNode]:
+        """Get all nodes in the chart."""
+        return self._chart.nodes
+
+    @property
+    def edges(self) -> list[ChartEdge]:
+        """Get all edges in the chart."""
+        return self._chart.edges
+
+    @property
+    def logics(self) -> list[ChartLogic]:
+        """Get all logic configurations."""
+        return self._chart.logics
+
+    @property
+    def startnode(self) -> str | None:
+        """Get start node ID."""
+        return self._chart.startnode
+
+    @startnode.setter
+    def startnode(self, nid: str | None) -> None:
+        """Set start node ID."""
+        self._chart.startnode = nid
+
+    def addNode(self, node: ChartNode) -> None:
+        """Add a node to the chart."""
+        self._chart.addNode(node)
+
+    def removeNode(self, nid: str) -> ChartNode | None:
+        """Remove a node and return it, or None if not found."""
+        return self._chart.removeNode(nid)
+
+    def getNode(self, nid: str) -> ChartNode | None:
+        """Get node by ID."""
+        return self._chart.getNode(nid)
+
+    def addEdge(self, edge: ChartEdge) -> None:
+        """Add an edge to the chart."""
+        self._chart.addEdge(edge)
+
+    def removeEdge(self, eid: str) -> ChartEdge | None:
+        """Remove an edge and return it, or None if not found."""
+        return self._chart.removeEdge(eid)
+
+    def getEdge(self, eid: str) -> ChartEdge | None:
+        """Get edge by ID."""
+        return self._chart.getEdge(eid)
+
+    def addLogic(self, logic: ChartLogic) -> None:
+        """Add logic configuration for a node."""
+        self._chart.addLogic(logic)
+
+    def getLogic(self, nid: str) -> ChartLogic | None:
+        """Get logic configuration for node."""
+        return self._chart.getLogic(nid)
+
+    def clearChart(self) -> None:
+        """Clear all nodes, edges and logics."""
+        self._chart.clearChart()
+
+    def getOutgoing(self, nid: str) -> list[ChartEdge]:
+        """Get all outgoing edges from a node."""
+        return self._chart.getOutgoing(nid)
+
+    def getIncoming(self, nid: str) -> list[ChartEdge]:
+        """Get all incoming edges to a node."""
+        return self._chart.getIncoming(nid)
+
+    def getConnected(self, nid: str) -> list[str]:
+        """Get IDs of all nodes connected to given node."""
+        return self._chart.getConnected(nid)
+
+    def validChart(self) -> tuple[bool, str]:
+        """
+        Validate chart integrity.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        return self._chart.validChart()
+
+    def fromJson(self, data: dict[str, Any]) -> 'QFlowChart':
+        """
+        Load chart from JSON format.
+
+        Args:
+            data: JSON data as dict
+
+        Returns:
+            Self for chaining
+        """
+        self._chart.fromJson(data)
+        return self
+
+    def toJson(self) -> dict[str, Any]:
+        """
+        Export chart to qnode JSON format.
+
+        Returns:
+            Dict compatible with qnode import
+        """
+        return self._chart.toJson()
+
+    def toStage(self, inst: Any | None = None) -> 'Stage':
+        """
+        Create qfsm Stage instance from chart.
+
+        Args:
+            inst: Optional bound instance
+
+        Returns:
+            qfsm Stage instance
+        """
+        return self._chart.toStage(inst)
+
+    def toLogic(self, inst: Any | None = None) -> 'Logic':
+        """
+        Create qfsm Logic instance from chart.
+
+        Args:
+            inst: Optional bound instance
+
+        Returns:
+            qfsm Logic instance
+        """
+        return self._chart.toLogic(inst)
+
+    def fromStage(self, stage: 'Stage') -> 'QFlowChart':
+        """
+        Load chart from chartflow.fsm Stage instance.
+
+        Args:
+            stage: qfsm Stage instance to parse
+
+        Returns:
+            Self for chaining
+        """
+        self._chart.fromStage(stage)
+        return self
+
+    def fromLogic(self, logic: 'Logic') -> 'QFlowChart':
+        """
+        Load chart from chartflow.fsm Logic instance.
+
+        Args:
+            logic: qfsm Logic instance to parse
+
+        Returns:
+            Self for chaining
+        """
+        self._chart.fromLogic(logic)
+        return self
+
+
+__all__ = [
+    "QFlowChart",
+]