@geenius/ai-workflow 0.1.0

package/packages/react/src/components/StepConnector.tsx

@@ -0,0 +1,47 @@
+// @geenius-ai-workflow/react — components/StepConnector.tsx
+
+export interface StepConnectorProps {
+  from: { x: number; y: number }
+  to: { x: number; y: number }
+  label?: string
+  isActive?: boolean
+}
+
+const NODE_WIDTH = 200
+const NODE_HEIGHT = 80
+
+export function StepConnector({ from, to, label, isActive }: StepConnectorProps) {
+  const x1 = from.x + NODE_WIDTH
+  const y1 = from.y + NODE_HEIGHT / 2
+  const x2 = to.x
+  const y2 = to.y + NODE_HEIGHT / 2
+  const midX = (x1 + x2) / 2
+
+  return (
+    <g data-workflow="connector" data-active={isActive || undefined}>
+      <path
+        d={`M ${x1} ${y1} C ${midX} ${y1}, ${midX} ${y2}, ${x2} ${y2}`}
+        fill="none"
+        stroke={isActive ? 'oklch(0.7 0.2 145)' : 'oklch(0.5 0.02 260)'}
+        strokeWidth={isActive ? 3 : 2}
+        markerEnd="url(#arrowhead)"
+      />
+      {label && (
+        <text
+          x={midX}
+          y={(y1 + y2) / 2 - 8}
+          textAnchor="middle"
+          fill="oklch(0.7 0.02 260)"
+          fontSize="12"
+        >
+          {label}
+        </text>
+      )}
+      <defs>
+        <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto">
+          <polygon points="0 0, 10 3.5, 0 7" fill="oklch(0.5 0.02 260)" />
+        </marker>
+      </defs>
+    </g>
+  )
+}

package/packages/react/src/components/StepNode.tsx

@@ -0,0 +1,38 @@
+// @geenius-ai-workflow/react — components/StepNode.tsx
+import type { WorkflowStepDef, StepType } from '@geenius-ai-workflow/shared'
+
+const STEP_ICONS: Record<StepType, string> = {
+  'llm-call': '🤖', transform: '⚙️', condition: '🔀', 'human-approval': '👤',
+  webhook: '🌐', delay: '⏱️', parallel: '⚡', loop: '🔄', 'sub-workflow': '📋', custom: '🔧',
+}
+
+export interface StepNodeProps {
+  step: WorkflowStepDef
+  isSelected?: boolean
+  status?: string
+  onClick?: () => void
+}
+
+export function StepNode({ step, isSelected, status, onClick }: StepNodeProps) {
+  return (
+    <div
+      data-workflow="step-node"
+      data-step-type={step.type}
+      data-selected={isSelected || undefined}
+      data-status={status}
+      role="button"
+      tabIndex={0}
+      onClick={onClick}
+      onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') onClick?.() }}
+      style={step.position ? { position: 'absolute', left: step.position.x, top: step.position.y } : undefined}
+    >
+      <div data-workflow="step-header">
+        <span data-workflow="step-icon">{STEP_ICONS[step.type]}</span>
+        <span data-workflow="step-name">{step.name}</span>
+      </div>
+      <div data-workflow="step-type-badge">{step.type}</div>
+      {step.optional && <span data-workflow="step-optional-badge">Optional</span>}
+      {step.retries && <span data-workflow="step-retry-badge">↻ {step.retries.maxAttempts}</span>}
+    </div>
+  )
+}

package/packages/react/src/components/StepPalette.tsx

@@ -0,0 +1,48 @@
+// @geenius-ai-workflow/react — components/StepPalette.tsx
+import type { StepType } from '@geenius-ai-workflow/shared'
+
+export interface StepPaletteItem {
+  type: StepType
+  label: string
+  icon: string
+  description: string
+}
+
+const PALETTE_ITEMS: StepPaletteItem[] = [
+  { type: 'llm-call', label: 'LLM Call', icon: '🤖', description: 'Call an AI model' },
+  { type: 'transform', label: 'Transform', icon: '⚙️', description: 'Transform data' },
+  { type: 'condition', label: 'Condition', icon: '🔀', description: 'If/else branching' },
+  { type: 'human-approval', label: 'Approval', icon: '👤', description: 'Human approval gate' },
+  { type: 'webhook', label: 'Webhook', icon: '🌐', description: 'HTTP request' },
+  { type: 'delay', label: 'Delay', icon: '⏱️', description: 'Wait for duration' },
+  { type: 'parallel', label: 'Parallel', icon: '⚡', description: 'Run steps in parallel' },
+  { type: 'loop', label: 'Loop', icon: '🔄', description: 'Iterate over items' },
+  { type: 'sub-workflow', label: 'Sub-workflow', icon: '📋', description: 'Run another workflow' },
+  { type: 'custom', label: 'Custom', icon: '🔧', description: 'Custom handler' },
+]
+
+export interface StepPaletteProps {
+  onAddStep: (type: StepType) => void
+}
+
+export function StepPalette({ onAddStep }: StepPaletteProps) {
+  return (
+    <div data-workflow="step-palette" role="list" aria-label="Available step types">
+      <h3 data-workflow="palette-title">Steps</h3>
+      {PALETTE_ITEMS.map(item => (
+        <button
+          key={item.type}
+          data-workflow="palette-item"
+          role="listitem"
+          onClick={() => onAddStep(item.type)}
+        >
+          <span data-workflow="palette-icon">{item.icon}</span>
+          <div data-workflow="palette-info">
+            <span data-workflow="palette-label">{item.label}</span>
+            <span data-workflow="palette-desc">{item.description}</span>
+          </div>
+        </button>
+      ))}
+    </div>
+  )
+}

package/packages/react/src/components/WorkflowCanvas.tsx

@@ -0,0 +1,42 @@
+// @geenius-ai-workflow/react — components/WorkflowCanvas.tsx
+import type { WorkflowDefinition, WorkflowStepDef } from '@geenius-ai-workflow/shared'
+import { StepNode } from './StepNode'
+import { StepConnector } from './StepConnector'
+
+export interface WorkflowCanvasProps {
+  definition: WorkflowDefinition
+  selectedStepId: string | null
+  onSelectStep: (id: string | null) => void
+  onMoveStep?: (stepId: string, pos: { x: number; y: number }) => void
+}
+
+export function WorkflowCanvas({ definition, selectedStepId, onSelectStep, onMoveStep }: WorkflowCanvasProps) {
+  return (
+    <div data-workflow="canvas" role="application" aria-label="Workflow canvas">
+      <svg data-workflow="connections-layer" style={{ position: 'absolute', inset: 0, pointerEvents: 'none' }}>
+        {definition.connections.map((conn, i) => {
+          const from = definition.steps.find(s => s.id === conn.fromStepId)
+          const to = definition.steps.find(s => s.id === conn.toStepId)
+          if (!from?.position || !to?.position) return null
+          return <StepConnector key={i} from={from.position} to={to.position} label={conn.label} />
+        })}
+      </svg>
+      <div data-workflow="nodes-layer">
+        {definition.steps.map(step => (
+          <StepNode
+            key={step.id}
+            step={step}
+            isSelected={selectedStepId === step.id}
+            onClick={() => onSelectStep(step.id === selectedStepId ? null : step.id)}
+          />
+        ))}
+      </div>
+      {definition.steps.length === 0 && (
+        <div data-workflow="canvas-empty">
+          <p data-workflow="empty-title">No steps yet</p>
+          <p data-workflow="empty-hint">Drag steps from the palette or use a template</p>
+        </div>
+      )}
+    </div>
+  )
+}

package/packages/react/src/components/WorkflowRunPanel.tsx

@@ -0,0 +1,64 @@
+// @geenius-ai-workflow/react — components/WorkflowRunPanel.tsx
+import type { WorkflowRun, StepResult } from '@geenius-ai-workflow/shared'
+import { formatCost } from '@geenius-ai-workflow/shared'
+
+export interface WorkflowRunPanelProps {
+  run: WorkflowRun | null
+  isRunning: boolean
+  onCancel?: () => void
+}
+
+const STATUS_ICONS: Record<string, string> = {
+  pending: '⏳', running: '🔄', completed: '✅', failed: '❌', skipped: '⏭️', 'waiting-approval': '👤',
+}
+
+export function WorkflowRunPanel({ run, isRunning, onCancel }: WorkflowRunPanelProps) {
+  if (!run) {
+    return (
+      <div data-workflow="run-panel">
+        <div data-workflow="run-empty"><p>No active run. Click "Run" to execute the workflow.</p></div>
+      </div>
+    )
+  }
+
+  const completedCount = run.stepResults.filter(s => s.status === 'completed').length
+  const totalCount = run.stepResults.length
+  const progress = totalCount > 0 ? Math.round((completedCount / totalCount) * 100) : 0
+  const totalCost = run.stepResults.reduce((sum, s) => sum + (s.costUsd ?? 0), 0)
+  const totalTokens = run.stepResults.reduce((sum, s) => sum + (s.tokens ?? 0), 0)
+  const duration = (run.completedAt ?? Date.now()) - run.startedAt
+
+  return (
+    <div data-workflow="run-panel" data-status={run.status}>
+      <div data-workflow="run-header">
+        <h3 data-workflow="run-title">
+          {STATUS_ICONS[run.status]} Run {run.status}
+        </h3>
+        {isRunning && onCancel && (
+          <button data-workflow="run-cancel" onClick={onCancel}>⏹ Cancel</button>
+        )}
+      </div>
+      <div data-workflow="run-progress">
+        <div data-workflow="run-progress-bar">
+          <div data-workflow="run-progress-fill" style={{ width: `${progress}%` }} />
+        </div>
+        <span data-workflow="run-progress-text">{completedCount}/{totalCount} steps ({progress}%)</span>
+      </div>
+      <div data-workflow="run-stats">
+        <span data-workflow="run-stat">⏱ {(duration / 1000).toFixed(1)}s</span>
+        {totalTokens > 0 && <span data-workflow="run-stat">🪙 {totalTokens.toLocaleString()} tokens</span>}
+        {totalCost > 0 && <span data-workflow="run-stat">💰 {formatCost(totalCost)}</span>}
+      </div>
+      {run.error && <div data-workflow="run-error" role="alert">{run.error}</div>}
+      <ul data-workflow="run-steps">
+        {run.stepResults.map(r => (
+          <li key={r.stepId} data-workflow="run-step-item" data-status={r.status}>
+            <span data-workflow="run-step-icon">{STATUS_ICONS[r.status]}</span>
+            <span data-workflow="run-step-name">{r.stepName}</span>
+            <span data-workflow="run-step-duration">{r.durationMs}ms</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}

package/packages/react/src/components/WorkflowToolbar.tsx

@@ -0,0 +1,43 @@
+// @geenius-ai-workflow/react — components/WorkflowToolbar.tsx
+
+export interface WorkflowToolbarProps {
+  workflowName: string
+  isDirty: boolean
+  isRunning: boolean
+  canUndo: boolean
+  canRedo: boolean
+  onSave: () => void
+  onRun: () => void
+  onCancel?: () => void
+  onUndo: () => void
+  onRedo: () => void
+  onExport?: () => void
+}
+
+export function WorkflowToolbar(props: WorkflowToolbarProps) {
+  return (
+    <div data-workflow="toolbar" role="toolbar" aria-label="Workflow actions">
+      <div data-workflow="toolbar-left">
+        <h2 data-workflow="toolbar-title">{props.workflowName}</h2>
+        {props.isDirty && <span data-workflow="toolbar-dirty">●</span>}
+      </div>
+      <div data-workflow="toolbar-center">
+        <button data-workflow="toolbar-btn" onClick={props.onUndo} disabled={!props.canUndo} title="Undo">↶</button>
+        <button data-workflow="toolbar-btn" onClick={props.onRedo} disabled={!props.canRedo} title="Redo">↷</button>
+      </div>
+      <div data-workflow="toolbar-right">
+        {props.onExport && (
+          <button data-workflow="toolbar-btn-secondary" onClick={props.onExport}>📤 Export</button>
+        )}
+        <button data-workflow="toolbar-btn-secondary" onClick={props.onSave} disabled={!props.isDirty}>
+          💾 Save
+        </button>
+        {props.isRunning ? (
+          <button data-workflow="toolbar-btn-danger" onClick={props.onCancel}>⏹ Stop</button>
+        ) : (
+          <button data-workflow="toolbar-btn-primary" onClick={props.onRun}>▶ Run</button>
+        )}
+      </div>
+    </div>
+  )
+}

package/packages/react/src/components/index.ts

@@ -0,0 +1,9 @@
+// @geenius-ai-workflow/react — components/index.ts
+export { WorkflowCanvas, type WorkflowCanvasProps } from './WorkflowCanvas'
+export { StepNode, type StepNodeProps } from './StepNode'
+export { StepConnector, type StepConnectorProps } from './StepConnector'
+export { StepConfigPanel, type StepConfigPanelProps } from './StepConfigPanel'
+export { WorkflowRunPanel, type WorkflowRunPanelProps } from './WorkflowRunPanel'
+export { ApprovalModal, type ApprovalModalProps } from './ApprovalModal'
+export { WorkflowToolbar, type WorkflowToolbarProps } from './WorkflowToolbar'
+export { StepPalette, type StepPaletteProps } from './StepPalette'

package/packages/react/src/hooks/index.ts

@@ -0,0 +1,10 @@
+// @geenius-ai-workflow/react — src/hooks/index.ts
+export { useWorkflow } from './useWorkflow'
+export type { UseWorkflowOptions } from './useWorkflow'
+export { useWorkflowBuilder } from './useWorkflowBuilder'
+export { useWorkflowRun } from './useWorkflowRun'
+export type { UseWorkflowRunOptions } from './useWorkflowRun'
+export { useWorkflowStep } from './useWorkflowStep'
+export { useApprovalGate } from './useApprovalGate'
+export type { ApprovalRequest } from './useApprovalGate'
+export { useWorkflowTemplates } from './useWorkflowTemplates'

package/packages/react/src/hooks/useApprovalGate.ts

@@ -0,0 +1,59 @@
+// @geenius-ai-workflow/react — src/hooks/useApprovalGate.ts
+import { useState, useCallback } from 'react'
+
+export interface ApprovalRequest {
+  id: string
+  stepId: string
+  message: string
+  requestedAt: number
+  approvers?: string[]
+}
+
+export function useApprovalGate() {
+  const [pendingApprovals, setPendingApprovals] = useState<ApprovalRequest[]>([])
+  const [history, setHistory] = useState<Array<ApprovalRequest & { decision: 'approved' | 'rejected'; decidedAt: number }>>([])
+
+  const requestApproval = useCallback((stepId: string, message: string, approvers?: string[]) => {
+    const request: ApprovalRequest = {
+      id: `approval_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+      stepId,
+      message,
+      requestedAt: Date.now(),
+      approvers,
+    }
+    setPendingApprovals(prev => [...prev, request])
+    return request.id
+  }, [])
+
+  const approve = useCallback((approvalId: string) => {
+    setPendingApprovals(prev => {
+      const request = prev.find(a => a.id === approvalId)
+      if (request) {
+        setHistory(h => [...h, { ...request, decision: 'approved', decidedAt: Date.now() }])
+      }
+      return prev.filter(a => a.id !== approvalId)
+    })
+  }, [])
+
+  const reject = useCallback((approvalId: string) => {
+    setPendingApprovals(prev => {
+      const request = prev.find(a => a.id === approvalId)
+      if (request) {
+        setHistory(h => [...h, { ...request, decision: 'rejected', decidedAt: Date.now() }])
+      }
+      return prev.filter(a => a.id !== approvalId)
+    })
+  }, [])
+
+  const clearHistory = useCallback(() => setHistory([]), [])
+
+  return {
+    pendingApprovals,
+    history,
+    hasPending: pendingApprovals.length > 0,
+    requestApproval,
+    approve,
+    reject,
+    clearHistory,
+  }
+}

package/packages/react/src/hooks/useWorkflow.ts

@@ -0,0 +1,39 @@
+// @geenius-ai-workflow/react — src/hooks/useWorkflow.ts
+import { useState, useCallback } from 'react'
+import type { WorkflowDefinition, WorkflowRun, StepResult } from '@geenius-ai-workflow/shared'
+import { WorkflowEngine } from '@geenius-ai-workflow/shared'
+import type { WorkflowEngineOptions } from '@geenius-ai-workflow/shared'
+
+export interface UseWorkflowOptions extends WorkflowEngineOptions { }
+
+export function useWorkflow(options: UseWorkflowOptions) {
+    const [run, setRun] = useState<WorkflowRun | null>(null)
+    const [isRunning, setIsRunning] = useState(false)
+    const [error, setError] = useState<Error | null>(null)
+    const [stepResults, setStepResults] = useState<StepResult[]>([])
+
+    const engine = new WorkflowEngine({
+        ...options,
+        onStepComplete: (result) => {
+            setStepResults(prev => [...prev, result])
+            options.onStepComplete?.(result)
+        },
+    })
+
+    const execute = useCallback(async (definition: WorkflowDefinition, input?: Record<string, unknown>) => {
+        setIsRunning(true); setError(null); setStepResults([])
+        try {
+            const result = await engine.execute(definition, input)
+            setRun(result)
+            return result
+        } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err))
+            setError(e); throw e
+        } finally { setIsRunning(false) }
+    }, [])
+
+    const cancel = useCallback(() => engine.cancel(), [])
+    const reset = useCallback(() => { setRun(null); setError(null); setStepResults([]) }, [])
+
+    return { execute, cancel, run, isRunning, error, stepResults, reset }
+}

package/packages/react/src/hooks/useWorkflowBuilder.ts

@@ -0,0 +1,121 @@
+// @geenius-ai-workflow/react — src/hooks/useWorkflowBuilder.ts
+import { useState, useCallback } from 'react'
+import type { WorkflowDefinition, WorkflowStepDef, StepConnection, WorkflowBuilderState } from '@geenius-ai-workflow/shared'
+
+const emptyDef = (): WorkflowDefinition => ({
+    id: crypto.randomUUID?.() ?? String(Date.now()),
+    name: 'New Workflow',
+    version: 1,
+    status: 'draft',
+    steps: [],
+    connections: [],
+    createdBy: '',
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+})
+
+export function useWorkflowBuilder(initial?: Partial<WorkflowDefinition>) {
+    const [state, setState] = useState<WorkflowBuilderState>({
+        definition: { ...emptyDef(), ...initial },
+        selectedStepId: null,
+        isDirty: false,
+        undoStack: [],
+        redoStack: [],
+    })
+
+    const pushUndo = useCallback(() => {
+        setState(prev => ({ ...prev, undoStack: [...prev.undoStack.slice(-20), prev.definition], redoStack: [] }))
+    }, [])
+
+    const addStep = useCallback((step: WorkflowStepDef) => {
+        pushUndo()
+        setState(prev => ({
+            ...prev,
+            isDirty: true,
+            definition: { ...prev.definition, steps: [...prev.definition.steps, step], updatedAt: Date.now() },
+        }))
+    }, [pushUndo])
+
+    const removeStep = useCallback((stepId: string) => {
+        pushUndo()
+        setState(prev => ({
+            ...prev,
+            isDirty: true,
+            definition: {
+                ...prev.definition,
+                steps: prev.definition.steps.filter(s => s.id !== stepId),
+                connections: prev.definition.connections.filter(c => c.fromStepId !== stepId && c.toStepId !== stepId),
+                updatedAt: Date.now(),
+            },
+            selectedStepId: prev.selectedStepId === stepId ? null : prev.selectedStepId,
+        }))
+    }, [pushUndo])
+
+    const updateStep = useCallback((stepId: string, updates: Partial<WorkflowStepDef>) => {
+        pushUndo()
+        setState(prev => ({
+            ...prev,
+            isDirty: true,
+            definition: {
+                ...prev.definition,
+                steps: prev.definition.steps.map(s => s.id === stepId ? { ...s, ...updates } : s),
+                updatedAt: Date.now(),
+            },
+        }))
+    }, [pushUndo])
+
+    const addConnection = useCallback((conn: StepConnection) => {
+        pushUndo()
+        setState(prev => ({
+            ...prev,
+            isDirty: true,
+            definition: { ...prev.definition, connections: [...prev.definition.connections, conn], updatedAt: Date.now() },
+        }))
+    }, [pushUndo])
+
+    const removeConnection = useCallback((fromStepId: string, toStepId: string) => {
+        pushUndo()
+        setState(prev => ({
+            ...prev,
+            isDirty: true,
+            definition: {
+                ...prev.definition,
+                connections: prev.definition.connections.filter(c => !(c.fromStepId === fromStepId && c.toStepId === toStepId)),
+                updatedAt: Date.now(),
+            },
+        }))
+    }, [pushUndo])
+
+    const selectStep = useCallback((stepId: string | null) => setState(prev => ({ ...prev, selectedStepId: stepId })), [])
+
+    const undo = useCallback(() => {
+        setState(prev => {
+            if (prev.undoStack.length === 0) return prev
+            const previous = prev.undoStack[prev.undoStack.length - 1]
+            return { ...prev, definition: previous, undoStack: prev.undoStack.slice(0, -1), redoStack: [prev.definition, ...prev.redoStack] }
+        })
+    }, [])
+
+    const redo = useCallback(() => {
+        setState(prev => {
+            if (prev.redoStack.length === 0) return prev
+            const next = prev.redoStack[0]
+            return { ...prev, definition: next, undoStack: [...prev.undoStack, prev.definition], redoStack: prev.redoStack.slice(1) }
+        })
+    }, [])
+
+    const setDefinition = useCallback((def: WorkflowDefinition) => {
+        setState(prev => ({ ...prev, definition: def, isDirty: false, undoStack: [], redoStack: [] }))
+    }, [])
+
+    return {
+        definition: state.definition,
+        selectedStepId: state.selectedStepId,
+        isDirty: state.isDirty,
+        canUndo: state.undoStack.length > 0,
+        canRedo: state.redoStack.length > 0,
+        addStep, removeStep, updateStep,
+        addConnection, removeConnection,
+        selectStep, undo, redo, setDefinition,
+    }
+}

package/packages/react/src/hooks/useWorkflowRun.ts

@@ -0,0 +1,75 @@
+// @geenius-ai-workflow/react — src/hooks/useWorkflowRun.ts
+import { useState, useCallback, useRef, useEffect } from 'react'
+import type { WorkflowRun, StepResult, RunStatus } from '@geenius-ai-workflow/shared'
+
+export interface UseWorkflowRunOptions {
+  /** Poll interval for checking run status (ms) */
+  pollIntervalMs?: number
+  /** Callback when a step completes */
+  onStepComplete?: (result: StepResult) => void
+  /** Callback when the run finishes */
+  onRunComplete?: (run: WorkflowRun) => void
+}
+
+export function useWorkflowRun(options: UseWorkflowRunOptions = {}) {
+  const [run, setRun] = useState<WorkflowRun | null>(null)
+  const [currentStepIndex, setCurrentStepIndex] = useState(0)
+  const [completedSteps, setCompletedSteps] = useState<StepResult[]>([])
+  const [status, setStatus] = useState<RunStatus>('pending')
+  const [progress, setProgress] = useState(0)
+  const [error, setError] = useState<string | null>(null)
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  const trackRun = useCallback((workflowRun: WorkflowRun) => {
+    setRun(workflowRun)
+    setStatus(workflowRun.status)
+    setCurrentStepIndex(workflowRun.currentStepIndex)
+    setCompletedSteps(workflowRun.stepResults)
+    setError(workflowRun.error ?? null)
+
+    const total = workflowRun.stepResults.length
+    const done = workflowRun.stepResults.filter(s => s.status === 'completed' || s.status === 'skipped').length
+    setProgress(total > 0 ? Math.round((done / total) * 100) : 0)
+
+    if (workflowRun.status === 'completed' || workflowRun.status === 'failed') {
+      options.onRunComplete?.(workflowRun)
+    }
+  }, [options.onRunComplete])
+
+  const updateStep = useCallback((result: StepResult) => {
+    setCompletedSteps(prev => {
+      const existing = prev.findIndex(s => s.stepId === result.stepId)
+      if (existing >= 0) {
+        const updated = [...prev]
+        updated[existing] = result
+        return updated
+      }
+      return [...prev, result]
+    })
+    setCurrentStepIndex(prev => prev + 1)
+    options.onStepComplete?.(result)
+  }, [options.onStepComplete])
+
+  const reset = useCallback(() => {
+    setRun(null)
+    setCurrentStepIndex(0)
+    setCompletedSteps([])
+    setStatus('pending')
+    setProgress(0)
+    setError(null)
+    if (timerRef.current) clearInterval(timerRef.current)
+  }, [])
+
+  useEffect(() => {
+    return () => { if (timerRef.current) clearInterval(timerRef.current) }
+  }, [])
+
+  return {
+    run, status, currentStepIndex, completedSteps,
+    progress, error,
+    trackRun, updateStep, reset,
+    isRunning: status === 'running',
+    isComplete: status === 'completed',
+    isFailed: status === 'failed',
+  }
+}

package/packages/react/src/hooks/useWorkflowStep.ts

@@ -0,0 +1,52 @@
+// @geenius-ai-workflow/react — src/hooks/useWorkflowStep.ts
+import { useState, useCallback, useMemo } from 'react'
+import type { WorkflowStepDef, StepResult, StepStatus, StepConfig } from '@geenius-ai-workflow/shared'
+
+export function useWorkflowStep(stepDef: WorkflowStepDef) {
+  const [status, setStatus] = useState<StepStatus>('pending')
+  const [output, setOutput] = useState<unknown>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [durationMs, setDurationMs] = useState(0)
+
+  const updateFromResult = useCallback((result: StepResult) => {
+    setStatus(result.status)
+    setOutput(result.output ?? null)
+    setError(result.error ?? null)
+    setDurationMs(result.durationMs)
+  }, [])
+
+  const reset = useCallback(() => {
+    setStatus('pending')
+    setOutput(null)
+    setError(null)
+    setDurationMs(0)
+  }, [])
+
+  const icon = useMemo(() => {
+    const map: Record<string, string> = {
+      'llm-call': '🤖', 'transform': '⚙️', 'condition': '🔀',
+      'human-approval': '👤', 'webhook': '🌐', 'delay': '⏱️',
+      'parallel': '⚡', 'loop': '🔄', 'sub-workflow': '📋', 'custom': '🔧',
+    }
+    return map[stepDef.type] ?? '📦'
+  }, [stepDef.type])
+
+  const statusColor = useMemo(() => {
+    const map: Record<StepStatus, string> = {
+      pending: 'gray', running: 'blue', completed: 'green',
+      failed: 'red', skipped: 'orange', 'waiting-approval': 'purple',
+    }
+    return map[status]
+  }, [status])
+
+  return {
+    stepDef, status, output, error, durationMs,
+    icon, statusColor,
+    updateFromResult, reset,
+    isComplete: status === 'completed',
+    isRunning: status === 'running',
+    isFailed: status === 'failed',
+    isWaiting: status === 'waiting-approval',
+    config: stepDef.config as StepConfig,
+  }
+}