feat(agentflow): update flow date change & save handlings and enhance examples

- Introduced FlowStatePanel to display live flow data and saved snapshots in a resizable side panel.
- Updated BasicExample and CustomUIExample to integrate FlowStatePanel for improved user experience.
- Enhanced keyboard shortcuts for saving flow data with Cmd+S and Ctrl+S functionality.
- Updated coverage thresholds in jest.config.js to include new FlowStatePanel hooks.
- Revised TESTS.md to reflect changes in testing status for useFlowHandlers and related components.

Author: jocelynlin-wd

packages/agentflow/TESTS.md

@@ -36,7 +36,7 @@ These modules carry the highest risk. Test in the same PR when modifying.
 | `src/infrastructure/api/nodes.ts` | `getAllNodes`, `getNodeByName`, `getNodeIconUrl` | ✅ Done |
 | `src/infrastructure/store/AgentflowContext.tsx` | `agentflowReducer` (all actions), `normalizeNodes`. Remaining: `deleteNode()`, `duplicateNode()`, `updateNodeData()`, `getFlowData()` | 🟡 Partial |
 | `src/useAgentflow.ts` | `getFlow()`, `toJSON()`, `validate()`, `addNode()`, `clear()` | ⬜ Not yet — thin wrapper |
-| `src/features/canvas/hooks/useFlowHandlers.ts` | `onConnect`, `onNodesChange`, `onEdgesChange`, `onAddNode` | ⬜ Not yet — coupled to ReactFlow |
+| `src/features/canvas/hooks/useFlowHandlers.ts` | `handleConnect`, `handleNodesChange`, `handleEdgesChange`, `handleAddNode` — synchronous `onFlowChange` callbacks, dirty tracking, viewport resolution, change filtering | ✅ Done |
 
 ### Tier 2 — Feature Hooks & Dialogs
 
@@ -70,7 +70,7 @@ Mostly JSX with minimal logic. Only add tests if business logic is introduced.
 | `src/atoms/NodeInputHandler.tsx` | If input rendering or position calculation logic changes | ⬜ Not yet |
 | `src/features/canvas/components/ConnectionLine.tsx` | If edge label determination logic becomes more complex | ⬜ Not yet |
 | `src/features/canvas/components/NodeStatusIndicator.tsx` | If status-to-color/icon mapping expands | ⬜ Not yet |
-| `src/Agentflow.tsx` | Integration test — dark mode, ThemeProvider, CSS variables, header rendering, generate flow dialog, imperative ref | ✅ Done |
+| `src/Agentflow.tsx` | Integration test — dark mode, ThemeProvider, CSS variables, header rendering, keyboard shortcuts (Cmd+S / Ctrl+S save), generate flow dialog, imperative ref | ✅ Done |
 
 Files that are pure styling or data constants (`styled.ts`, `nodeIcons.ts`, `MainCard.tsx`, `Input.tsx`, etc.) do not need dedicated tests.
 
@@ -127,6 +127,7 @@ Key features:
 -   **Coverage thresholds**: uniform 80% floor (`branches`, `functions`, `lines`, `statements`) enforced per-path:
     -   `./src/Agentflow.tsx`
     -   `./src/core/`
+    -   `./src/features/canvas/hooks/useFlowHandlers.ts`
     -   `./src/features/node-palette/search.ts`
     -   `./src/infrastructure/api/`
 -   **Coverage exclusions**:

packages/agentflow/examples/src/App.tsx

@@ -100,7 +100,7 @@ function LoadingFallback() {
 
 export default function App() {
     const [selectedExample, setSelectedExample] = useState<ExampleId>('basic')
-    const [showProps, setShowProps] = useState(true)
+    const [showProps, setShowProps] = useState(false)
     // Config loaded from environment variables
 
     const currentExample = examples.find((e) => e.id === selectedExample)

packages/agentflow/examples/src/FlowStatePanel.tsx

@@ -0,0 +1,192 @@
+/**
+ * FlowStatePanel Component
+ *
+ * Displays live onFlowChange data and saved flow snapshots
+ * in a dark-themed, resizable side panel with copy support.
+ */
+
+import { useCallback, useRef, useState } from 'react'
+
+import type { FlowData } from '@flowiseai/agentflow'
+
+interface FlowStatePanelProps {
+    currentFlow: FlowData | null
+    savedFlow: FlowData | null
+    changeCount: number
+}
+
+export function FlowStatePanel({ currentFlow, savedFlow, changeCount }: FlowStatePanelProps) {
+    const [tab, setTab] = useState<'live' | 'saved'>('live')
+    const [copied, setCopied] = useState(false)
+    const [width, setWidth] = useState(300)
+    const dragging = useRef(false)
+    const flow = tab === 'live' ? currentFlow : savedFlow
+
+    const resizeBy = useCallback((delta: number) => {
+        setWidth((w) => Math.max(200, Math.min(800, w + delta)))
+    }, [])
+
+    const handleMouseDown = useCallback(
+        (e: React.MouseEvent) => {
+            e.preventDefault()
+            dragging.current = true
+            const startX = e.clientX
+            const startWidth = width
+
+            const onMouseMove = (moveEvent: MouseEvent) => {
+                if (!dragging.current) return
+                const newWidth = Math.max(200, Math.min(800, startWidth + (startX - moveEvent.clientX)))
+                setWidth(newWidth)
+            }
+
+            const onMouseUp = () => {
+                dragging.current = false
+                document.removeEventListener('mousemove', onMouseMove)
+                document.removeEventListener('mouseup', onMouseUp)
+                document.body.style.cursor = ''
+                document.body.style.userSelect = ''
+            }
+
+            document.addEventListener('mousemove', onMouseMove)
+            document.addEventListener('mouseup', onMouseUp)
+            document.body.style.cursor = 'col-resize'
+            document.body.style.userSelect = 'none'
+        },
+        [width]
+    )
+
+    const handleKeyDown = useCallback(
+        (e: React.KeyboardEvent) => {
+            if (e.key === 'ArrowLeft') {
+                e.preventDefault()
+                resizeBy(-20)
+            } else if (e.key === 'ArrowRight') {
+                e.preventDefault()
+                resizeBy(20)
+            }
+        },
+        [resizeBy]
+    )
+
+    return (
+        <div
+            style={{
+                width: `${width}px`,
+                minHeight: 0,
+                background: '#1e1e2e',
+                color: '#cdd6f4',
+                display: 'flex',
+                flexDirection: 'column',
+                fontSize: '13px',
+                fontFamily: 'monospace',
+                borderLeft: '1px solid #313244',
+                overflow: 'hidden',
+                position: 'relative'
+            }}
+        >
+            {/* Drag handle */}
+            <button
+                aria-label='Resize panel'
+                onMouseDown={handleMouseDown}
+                onKeyDown={handleKeyDown}
+                style={{
+                    position: 'absolute',
+                    left: 0,
+                    top: 0,
+                    bottom: 0,
+                    width: '4px',
+                    cursor: 'col-resize',
+                    zIndex: 10,
+                    padding: 0,
+                    border: 'none',
+                    background: 'transparent'
+                }}
+            />
+            {/* Tabs */}
+            <div style={{ display: 'flex', borderBottom: '1px solid #313244' }}>
+                <button
+                    onClick={() => setTab('live')}
+                    style={{
+                        flex: 1,
+                        padding: '10px',
+                        background: tab === 'live' ? '#313244' : 'transparent',
+                        color: tab === 'live' ? '#cba6f7' : '#6c7086',
+                        border: 'none',
+                        cursor: 'pointer',
+                        fontFamily: 'monospace',
+                        fontSize: '12px',
+                        fontWeight: 600
+                    }}
+                >
+                    onFlowChange ({changeCount})
+                </button>
+                <button
+                    onClick={() => setTab('saved')}
+                    style={{
+                        flex: 1,
+                        padding: '10px',
+                        background: tab === 'saved' ? '#313244' : 'transparent',
+                        color: tab === 'saved' ? '#a6e3a1' : '#6c7086',
+                        border: 'none',
+                        cursor: 'pointer',
+                        fontFamily: 'monospace',
+                        fontSize: '12px',
+                        fontWeight: 600
+                    }}
+                >
+                    onSave {savedFlow ? '(1)' : '(0)'}
+                </button>
+            </div>
+
+            {/* Summary stats + copy button */}
+            {flow && (
+                <div
+                    style={{ display: 'flex', alignItems: 'center', gap: '12px', padding: '10px 14px', borderBottom: '1px solid #313244' }}
+                >
+                    <span>
+                        <span style={{ color: '#89b4fa' }}>nodes:</span> {flow.nodes.length}
+                    </span>
+                    <span>
+                        <span style={{ color: '#f9e2af' }}>edges:</span> {flow.edges.length}
+                    </span>
+                    <button
+                        onClick={() => {
+                            navigator.clipboard.writeText(JSON.stringify(flow, null, 2))
+                            setCopied(true)
+                            setTimeout(() => setCopied(false), 1500)
+                        }}
+                        style={{
+                            marginLeft: 'auto',
+                            padding: '3px 10px',
+                            background: copied ? '#a6e3a1' : '#45475a',
+                            color: copied ? '#1e1e2e' : '#cdd6f4',
+                            border: 'none',
+                            borderRadius: '4px',
+                            cursor: 'pointer',
+                            fontFamily: 'monospace',
+                            fontSize: '11px',
+                            transition: 'all 0.15s'
+                        }}
+                    >
+                        {copied ? 'Copied!' : 'Copy'}
+                    </button>
+                </div>
+            )}
+
+            {/* JSON payload */}
+            <div style={{ flex: 1, overflow: 'auto', padding: '10px 14px' }}>
+                {flow ? (
+                    <pre style={{ margin: 0, whiteSpace: 'pre-wrap', wordBreak: 'break-word', lineHeight: 1.5 }}>
+                        {JSON.stringify(flow, null, 2)}
+                    </pre>
+                ) : (
+                    <div style={{ color: '#6c7086', padding: '20px 0', textAlign: 'center' }}>
+                        {tab === 'live'
+                            ? 'Interact with the canvas to see live flow data.'
+                            : 'Click Save or press Cmd+S to capture a snapshot.'}
+                    </div>
+                )}
+            </div>
+        </div>
+    )
+}

packages/agentflow/examples/src/demos/BasicExample.tsx

@@ -1,15 +1,17 @@
 /**
  * Basic Example
  *
- * Demonstrates basic @flowiseai/agentflow usage with imperative methods.
+ * Demonstrates basic @flowiseai/agentflow usage with imperative methods,
+ * onFlowChange tracking, and save flow functionality.
  */
 
-import { useRef, useState } from 'react'
+import { useCallback, useRef, useState } from 'react'
 
 import type { AgentFlowInstance, FlowData, ValidationResult } from '@flowiseai/agentflow'
 import { Agentflow } from '@flowiseai/agentflow'
 
 import { apiBaseUrl, token } from '../config'
+import { FlowStatePanel } from '../FlowStatePanel'
 
 // Example flow data
 const initialFlow: FlowData = {
@@ -33,18 +35,22 @@ const initialFlow: FlowData = {
 }
 
 export function BasicExample() {
-    // Config loaded from environment variables
     const agentflowRef = useRef<AgentFlowInstance>(null)
     const [validationResult, setValidationResult] = useState<ValidationResult | null>(null)
+    const [currentFlow, setCurrentFlow] = useState<FlowData | null>(null)
+    const [savedFlow, setSavedFlow] = useState<FlowData | null>(null)
+    const [changeCount, setChangeCount] = useState(0)
 
-    const handleFlowChange = (flow: FlowData) => {
-        console.log('Flow changed:', flow)
-    }
+    const handleFlowChange = useCallback((flow: FlowData) => {
+        setCurrentFlow(flow)
+        setChangeCount((c) => c + 1)
+        console.log('onFlowChange:', flow)
+    }, [])
 
-    const handleSave = (flow: FlowData) => {
-        console.log('Flow saved:', flow)
-        alert('Flow saved! Check console for data.')
-    }
+    const handleSave = useCallback((flow: FlowData) => {
+        setSavedFlow(flow)
+        console.log('onSave:', flow)
+    }, [])
 
     const handleValidate = () => {
         if (agentflowRef.current) {
@@ -98,17 +104,20 @@ export function BasicExample() {
                 )}
             </div>
 
-            {/* Canvas */}
-            <div style={{ flex: 1 }}>
-                <Agentflow
-                    ref={agentflowRef}
-                    apiBaseUrl={apiBaseUrl}
-                    token={token ?? undefined}
-                    initialFlow={initialFlow}
-                    onFlowChange={handleFlowChange}
-                    onSave={handleSave}
-                    showDefaultHeader={true}
-                />
+            {/* Canvas + Flow State Panel */}
+            <div style={{ flex: 1, display: 'flex', minHeight: 0 }}>
+                <div style={{ flex: 1 }}>
+                    <Agentflow
+                        ref={agentflowRef}
+                        apiBaseUrl={apiBaseUrl}
+                        token={token ?? undefined}
+                        initialFlow={initialFlow}
+                        onFlowChange={handleFlowChange}
+                        onSave={handleSave}
+                        showDefaultHeader={true}
+                    />
+                </div>
+                <FlowStatePanel currentFlow={currentFlow} savedFlow={savedFlow} changeCount={changeCount} />
             </div>
         </div>
     )

packages/agentflow/examples/src/demos/CustomUIExample.tsx

@@ -260,11 +260,11 @@ export function CustomUIExample() {
                     apiBaseUrl={apiBaseUrl}
                     token={token ?? undefined}
                     initialFlow={initialFlow}
-                    renderHeader={(props) => <CustomHeader {...props} />}
-                    renderNodePalette={(props) => <CustomPalette {...props} />}
+                    renderHeader={(props: HeaderRenderProps) => <CustomHeader {...props} />}
+                    renderNodePalette={(props: PaletteRenderProps) => <CustomPalette {...props} />}
                     showDefaultHeader={false}
                     showDefaultPalette={false}
-                    onSave={(flow) => {
+                    onSave={(flow: FlowData) => {
                         console.log('Saving flow:', flow)
                         alert('Flow saved! Check console.')
                     }}

packages/agentflow/jest.config.js

@@ -38,6 +38,7 @@ module.exports = {
     coverageThreshold: {
         './src/Agentflow.tsx': { branches: 80, functions: 80, lines: 80, statements: 80 },
         './src/core/': { branches: 80, functions: 80, lines: 80, statements: 80 },
+        './src/features/canvas/hooks/useFlowHandlers.ts': { branches: 80, functions: 80, lines: 80, statements: 80 },
         './src/features/node-palette/search.ts': { branches: 80, functions: 80, lines: 80, statements: 80 },
         './src/infrastructure/api/': { branches: 80, functions: 80, lines: 80, statements: 80 }
     },

packages/agentflow/src/Agentflow.test.tsx

@@ -305,6 +305,65 @@ describe('Agentflow Component', () => {
         })
     })
 
+    describe('Keyboard Shortcuts', () => {
+        it('should trigger save on Cmd+S', async () => {
+            const onSave = jest.fn()
+            const { container } = render(<Agentflow {...defaultProps} onSave={onSave} />)
+
+            await waitFor(() => {
+                expect(container.querySelector('.agentflow-container')).toBeInTheDocument()
+            })
+
+            fireEvent.keyDown(document, { key: 's', metaKey: true })
+
+            expect(onSave).toHaveBeenCalledTimes(1)
+            expect(onSave).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    nodes: expect.any(Array),
+                    edges: expect.any(Array)
+                })
+            )
+        })
+
+        it('should trigger save on Ctrl+S', async () => {
+            const onSave = jest.fn()
+            const { container } = render(<Agentflow {...defaultProps} onSave={onSave} />)
+
+            await waitFor(() => {
+                expect(container.querySelector('.agentflow-container')).toBeInTheDocument()
+            })
+
+            fireEvent.keyDown(document, { key: 's', ctrlKey: true })
+
+            expect(onSave).toHaveBeenCalledTimes(1)
+        })
+
+        it('should not trigger save on plain S key', async () => {
+            const onSave = jest.fn()
+            const { container } = render(<Agentflow {...defaultProps} onSave={onSave} />)
+
+            await waitFor(() => {
+                expect(container.querySelector('.agentflow-container')).toBeInTheDocument()
+            })
+
+            fireEvent.keyDown(document, { key: 's' })
+
+            expect(onSave).not.toHaveBeenCalled()
+        })
+
+        it('should not error on Cmd+S when no onSave callback is provided', async () => {
+            const { container } = render(<Agentflow {...defaultProps} />)
+
+            await waitFor(() => {
+                expect(container.querySelector('.agentflow-container')).toBeInTheDocument()
+            })
+
+            expect(() => {
+                fireEvent.keyDown(document, { key: 's', metaKey: true })
+            }).not.toThrow()
+        })
+    })
+
     describe('Generate Flow', () => {
         it('should open generate dialog when button is clicked', async () => {
             const { container, getByTestId } = render(<Agentflow {...defaultProps} />)