@stigmer/react 1.0.4 → 2.0.0

package/src/workflow/WorkflowExecutionGraph.tsx

@@ -0,0 +1,414 @@
+"use client";
+
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  ReactFlow,
+  Controls,
+  MiniMap,
+  Background,
+  BackgroundVariant,
+  MarkerType,
+  useReactFlow,
+  ReactFlowProvider,
+} from "@xyflow/react";
+import type { Node, NodeChange, Viewport } from "@xyflow/react";
+import { cn } from "@stigmer/theme";
+import { WorkflowNode } from "./WorkflowNode";
+import { CanvasTransitionEdge } from "./CanvasTransitionEdge";
+import { CANVAS_TASK_NODE_TYPE, CANVAS_TRANSITION_EDGE_TYPE } from "./workflow-graph-conversions";
+import type { CanvasTaskNodeData } from "./workflow-graph-conversions";
+import { WorkflowGraphModeProvider } from "./WorkflowGraphModeContext";
+import { useWorkflowExecutionGraph } from "./useWorkflowExecutionGraph";
+import type { UseWorkflowExecutionGraphReturn } from "./useWorkflowExecutionGraph";
+import type { DerivedTaskState } from "../internal/store/workflow-execution-event-store";
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { useFollowExecution, computeFollowSelection } from "./useFollowExecution";
+import { useActiveTaskName } from "./useActiveTaskName";
+import { useExecutionAnnouncements } from "./useExecutionAnnouncements";
+import { ExecutionActiveTaskIndicator } from "./ExecutionActiveTaskIndicator";
+import { getAnimationDuration } from "./motion-preference";
+
+/** Props for {@link WorkflowExecutionGraph}. */
+export interface WorkflowExecutionGraphProps {
+  /** ID of the workflow execution to visualize. */
+  readonly executionId: string;
+  /** Callback when a task node is selected or deselected. */
+  readonly onTaskSelect?: (taskName: string | null) => void;
+  /** When true, the viewport auto-pans to follow the currently running node. */
+  readonly followExecution?: boolean;
+  /**
+   * Pre-fetched execution from the parent. When provided, the graph
+   * skips its own execution fetch — eliminating duplicate API calls.
+   * Pass `undefined` (or omit) for standalone usage.
+   */
+  readonly execution?: WorkflowExecution | null;
+  /**
+   * Externally-derived task states from a shared event store. When
+   * provided, the graph skips its own event stream subscription.
+   * Pass `undefined` (or omit) for standalone usage.
+   */
+  readonly taskStates?: ReadonlyMap<string, DerivedTaskState>;
+  /**
+   * Callback invoked when the graph auto-selects a failed task on
+   * terminal executions. Wire this to the parent's selected-task
+   * state to keep sibling components (like the inspector) in sync.
+   */
+  readonly onAutoSelectTask?: (taskName: string) => void;
+  /**
+   * Pixel width of a panel that **overlays** (absolutely positioned over)
+   * the graph viewport, occluding the right side. The follow-execution
+   * camera offsets its center to keep the active node visually centered
+   * in the unoccluded area. Defaults to 0.
+   *
+   * When the panel is a **flex sibling** (e.g., inside `ResizableSplit`),
+   * the ReactFlow container already has the correct reduced width and
+   * `setCenter`/`fitView` operate within those bounds — set this to 0
+   * (the default) to avoid double-compensating the viewport offset.
+   */
+  readonly panelOffsetPx?: number;
+  /**
+   * Whether task nodes can be dragged to rearrange the layout.
+   * Useful for presentations and demos where the auto-layout is too
+   * dense. Drag positions are ephemeral (in-memory only) and reset
+   * when the underlying graph structure changes.
+   * @default false
+   */
+  readonly nodesDraggable?: boolean;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+const nodeTypes = {
+  [CANVAS_TASK_NODE_TYPE]: WorkflowNode,
+} as const;
+
+const edgeTypes = {
+  [CANVAS_TRANSITION_EDGE_TYPE]: CanvasTransitionEdge,
+} as const;
+
+const defaultEdgeOptions = {
+  markerEnd: { type: MarkerType.ArrowClosed, width: 16, height: 16 },
+};
+
+/**
+ * Read-only execution graph canvas for workflow executions.
+ *
+ * Reuses the same `WorkflowNode` / `NodeShell` node rendering system from
+ * the visual editor, wrapped in execution mode context to show live status
+ * overlays instead of editing affordances.
+ *
+ * Designed for embedding in both the Stigmer Console and third-party
+ * dashboards — no routing, auth, or app-shell dependencies (DD-004).
+ *
+ * @example
+ * ```tsx
+ * <WorkflowExecutionGraph
+ *   executionId="wex_abc123"
+ *   onTaskSelect={(name) => setInspectedTask(name)}
+ * />
+ * ```
+ */
+export const WorkflowExecutionGraph = memo(function WorkflowExecutionGraph(
+  props: WorkflowExecutionGraphProps,
+) {
+  return (
+    <ReactFlowProvider>
+      <WorkflowExecutionGraphInner {...props} />
+    </ReactFlowProvider>
+  );
+});
+
+const TERMINAL_EXECUTION_PHASES = new Set([3, 4, 5, 6]);
+
+function WorkflowExecutionGraphInner({
+  executionId,
+  onTaskSelect,
+  followExecution = false,
+  execution: externalExecution,
+  taskStates: externalTaskStates,
+  onAutoSelectTask,
+  panelOffsetPx = 0,
+  nodesDraggable: draggable = false,
+  className,
+}: WorkflowExecutionGraphProps) {
+  const graphState = useWorkflowExecutionGraph({
+    executionId,
+    execution: externalExecution,
+    taskStates: externalTaskStates,
+    onAutoSelectTask,
+    nodesDraggable: draggable,
+  });
+  const {
+    nodes,
+    edges,
+    isLoading,
+    error,
+    selectedTaskName,
+    setSelectedTaskName,
+    versionMismatch,
+    taskStates,
+    executionPhase,
+  } = graphState;
+
+  const { fitView } = useReactFlow();
+  const [didInitialFit, setDidInitialFit] = useState(false);
+  const isInitializedRef = useRef(false);
+  const didFitGuardRef = useRef(false);
+
+  // ── Ephemeral drag positions ───────────────────────────────────────
+  // Resets when the execution changes (navigating to a different run).
+  const [dragPositions, setDragPositions] = useState<Record<string, { x: number; y: number }>>({});
+
+  useEffect(() => {
+    setDragPositions({});
+  }, [executionId]);
+
+  const hasDragOverrides = draggable && Object.keys(dragPositions).length > 0;
+
+  const handleNodesChange = useCallback(
+    (changes: NodeChange[]) => {
+      if (!draggable) return;
+      const posChanges = changes.filter(
+        (c): c is NodeChange & { type: "position"; position: { x: number; y: number } } =>
+          c.type === "position" && "position" in c && c.position != null,
+      );
+      if (posChanges.length === 0) return;
+      setDragPositions((prev) => {
+        const next = { ...prev };
+        for (const c of posChanges) {
+          next[c.id] = c.position;
+        }
+        return next;
+      });
+    },
+    [draggable],
+  );
+
+  const handleResetLayout = useCallback(() => {
+    setDragPositions({});
+  }, []);
+
+  const performInitialFit = useCallback(() => {
+    if (didFitGuardRef.current) return;
+    didFitGuardRef.current = true;
+    fitView({ padding: 0.15, duration: getAnimationDuration(300) });
+    setDidInitialFit(true);
+  }, [fitView]);
+
+  // onInit fires when ReactFlow's container is measured and the
+  // viewport is ready — replacing the fragile 50ms setTimeout.
+  const handleInit = useCallback(() => {
+    isInitializedRef.current = true;
+    if (nodes.length > 0) {
+      performInitialFit();
+    }
+  }, [nodes.length, performInitialFit]);
+
+  // When nodes arrive after onInit (async data), fit once they're ready.
+  useEffect(() => {
+    if (isInitializedRef.current && nodes.length > 0) {
+      performInitialFit();
+    }
+  }, [nodes.length, performInitialFit]);
+
+  // Derive active task name stably from taskStates (not from nodes array — DD-010)
+  const activeTaskInfo = useActiveTaskName(taskStates);
+  const isTerminal = executionPhase != null && TERMINAL_EXECUTION_PHASES.has(executionPhase);
+
+  // Follow-execution state machine
+  const {
+    isFollowing,
+    enableFollow,
+    disableFollow,
+    handleMoveStart,
+  } = useFollowExecution({
+    enabled: followExecution,
+    activeTaskName: activeTaskInfo?.taskName ?? null,
+    nodes,
+    didInitialFit,
+    isTerminal,
+    panelOffsetPx,
+  });
+
+  // ── Follow-selection: auto-select the active task while following ──
+  // Couples node selection to the follow state machine so "Follow" means
+  // viewport centering + node highlighting + inspector display.
+  useEffect(() => {
+    const taskToSelect = computeFollowSelection({
+      isFollowing,
+      activeTaskName: activeTaskInfo?.taskName ?? null,
+      currentSelectedTask: selectedTaskName,
+    });
+    if (!taskToSelect) return;
+    setSelectedTaskName(taskToSelect);
+    onTaskSelect?.(taskToSelect);
+  }, [isFollowing, activeTaskInfo?.taskName, selectedTaskName, setSelectedTaskName, onTaskSelect]);
+
+  // Screen reader announcements for task state changes
+  const announcement = useExecutionAnnouncements(taskStates);
+
+  const handleNodeClick = useCallback(
+    (_event: React.MouseEvent, node: Node) => {
+      const data = node.data as CanvasTaskNodeData;
+      if (data.isSentinel) return;
+      const name = data.taskName;
+      const next = name === selectedTaskName ? null : name;
+      setSelectedTaskName(next);
+      onTaskSelect?.(next);
+      if (isFollowing) disableFollow();
+    },
+    [selectedTaskName, setSelectedTaskName, onTaskSelect, isFollowing, disableFollow],
+  );
+
+  const handlePaneClick = useCallback(() => {
+    setSelectedTaskName(null);
+    onTaskSelect?.(null);
+    if (isFollowing) disableFollow();
+  }, [setSelectedTaskName, onTaskSelect, isFollowing, disableFollow]);
+
+  const onMoveStart = useCallback(
+    (event: MouseEvent | TouchEvent | null, viewport: Viewport) => {
+      handleMoveStart(event, viewport);
+    },
+    [handleMoveStart],
+  );
+
+  // Mark selected node + apply drag position overrides
+  const nodesWithSelection = useMemo(
+    () =>
+      nodes.map((n) => {
+        const selected = (n.data as CanvasTaskNodeData).taskName === selectedTaskName;
+        const pos = dragPositions[n.id];
+        return pos
+          ? { ...n, selected, position: pos }
+          : selected !== n.selected
+            ? { ...n, selected }
+            : n;
+      }),
+    [nodes, selectedTaskName, dragPositions],
+  );
+
+  if (isLoading) {
+    return (
+      <div className={cn("flex h-full items-center justify-center", className)}>
+        <GraphLoadingSkeleton />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={cn("flex h-full flex-col items-center justify-center gap-2 px-6 text-center", className)}>
+        <p className="text-sm text-[var(--stgm-muted-foreground,#737373)]">{error}</p>
+      </div>
+    );
+  }
+
+  if (nodes.length === 0) {
+    return (
+      <div className={cn("flex h-full items-center justify-center text-sm text-[var(--stgm-muted-foreground,#737373)]", className)}>
+        No graph available for this execution
+      </div>
+    );
+  }
+
+  return (
+    <WorkflowGraphModeProvider mode="execution">
+      <div className={cn("relative h-full w-full", className)}>
+        {versionMismatch && (
+          <div className="absolute left-3 right-3 top-3 z-50 rounded-md border border-[var(--stgm-warning,#f59e0b)]/30 bg-[var(--stgm-warning,#f59e0b)]/5 px-3 py-2 text-xs text-[var(--stgm-foreground,#1a1a2e)]">
+            {versionMismatch}
+          </div>
+        )}
+
+        {/* Active task indicator — visible at any zoom level */}
+        {followExecution && activeTaskInfo && (
+          <ExecutionActiveTaskIndicator
+            activeTask={activeTaskInfo}
+            isFollowing={isFollowing}
+            onFollowToggle={isFollowing ? disableFollow : enableFollow}
+            onJumpToTask={() => enableFollow()}
+          />
+        )}
+
+        {/* Reset layout pill — shown when nodes have been manually repositioned */}
+        {hasDragOverrides && (
+          <button
+            type="button"
+            onClick={handleResetLayout}
+            className={cn(
+              "absolute left-3 z-50 rounded-full border border-[var(--stgm-border,#e5e5e5)] bg-[var(--stgm-background,#fff)] px-3 py-1 text-xs text-[var(--stgm-foreground,#1a1a2e)] shadow-sm transition-colors hover:bg-[var(--stgm-muted,#f5f5f5)]",
+              versionMismatch ? "top-12" : "top-3",
+            )}
+          >
+            Reset layout
+          </button>
+        )}
+
+        <ReactFlow
+          nodes={nodesWithSelection}
+          edges={edges}
+          nodeTypes={nodeTypes}
+          edgeTypes={edgeTypes}
+          defaultEdgeOptions={defaultEdgeOptions}
+          onInit={handleInit}
+          onNodeClick={handleNodeClick}
+          onPaneClick={handlePaneClick}
+          onMoveStart={onMoveStart}
+          onNodesChange={draggable ? handleNodesChange : undefined}
+          nodesDraggable={draggable}
+          nodesConnectable={false}
+          nodesFocusable={true}
+          elementsSelectable={true}
+          panOnDrag={true}
+          zoomOnScroll={true}
+          fitView={false}
+          minZoom={0.2}
+          maxZoom={2}
+          proOptions={{ hideAttribution: true }}
+          aria-label="Workflow execution graph. Use Tab to navigate between tasks."
+        >
+          <Background variant={BackgroundVariant.Dots} gap={16} size={1} />
+          <Controls showInteractive={false} />
+          <MiniMap
+            nodeColor={(node) => {
+              const data = node.data as CanvasTaskNodeData;
+              const status = data.executionState?.status;
+              if (status === "completed") return "var(--stgm-success, #22c55e)";
+              if (status === "failed") return "var(--stgm-destructive, #ef4444)";
+              if (status === "running") return "var(--stgm-primary, #6366f1)";
+              return "var(--stgm-muted, #e5e5e5)";
+            }}
+            pannable
+            zoomable
+          />
+        </ReactFlow>
+
+        {/* Screen reader live region for execution state announcements */}
+        <div
+          role="log"
+          aria-live="polite"
+          aria-atomic="false"
+          className="sr-only"
+        >
+          {announcement}
+        </div>
+      </div>
+    </WorkflowGraphModeProvider>
+  );
+}
+
+function GraphLoadingSkeleton() {
+  return (
+    <div className="flex flex-col items-center gap-3">
+      <div className="h-8 w-8 animate-pulse rounded-full bg-[var(--stgm-muted,#e5e5e5)]" />
+      <div className="h-3 w-24 animate-pulse rounded bg-[var(--stgm-muted,#e5e5e5)]" />
+      <div className="mt-2 flex gap-4">
+        <div className="h-10 w-32 animate-pulse rounded-md bg-[var(--stgm-muted,#e5e5e5)]" />
+        <div className="h-10 w-32 animate-pulse rounded-md bg-[var(--stgm-muted,#e5e5e5)]" />
+      </div>
+    </div>
+  );
+}
+
+export type { UseWorkflowExecutionGraphReturn, DerivedTaskState };

package/src/workflow/WorkflowExecutionHeader.tsx

@@ -7,6 +7,7 @@ import { cn } from "@stigmer/theme";
 import { WorkflowExecutionPhaseBadge } from "./WorkflowExecutionPhaseBadge";
 import type { UseWorkflowExecutionActionsReturn } from "./useWorkflowExecutionActions";
 import type { WorkflowEventStreamState, DerivedCostSummary } from "../internal/store/workflow-execution-event-store";
+import { formatDuration, formatMicroUsd } from "./format-utils";
 
 /** Props for {@link WorkflowExecutionHeader}. */
 export interface WorkflowExecutionHeaderProps {
@@ -18,6 +19,8 @@ export interface WorkflowExecutionHeaderProps {
   readonly onDiagnose?: () => void;
   /** Whether the diagnosis panel is currently active. */
   readonly isDiagnosing?: boolean;
+  /** Called when the user clicks "Compare with..." on a terminal execution. */
+  readonly onCompare?: () => void;
   readonly className?: string;
 }
 
@@ -35,6 +38,13 @@ const RUNNING_PHASES = new Set<ExecutionPhase>([
  * - Paused: Resume, Cancel
  * - Failed: Recover
  */
+const TERMINAL_PHASES = new Set<ExecutionPhase>([
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+]);
+
 export const WorkflowExecutionHeader = memo(function WorkflowExecutionHeader({
   execution,
   streamState,
@@ -42,6 +52,7 @@ export const WorkflowExecutionHeader = memo(function WorkflowExecutionHeader({
   actions,
   onDiagnose,
   isDiagnosing,
+  onCompare,
   className,
 }: WorkflowExecutionHeaderProps) {
   const phase = execution.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
@@ -93,6 +104,14 @@ export const WorkflowExecutionHeader = memo(function WorkflowExecutionHeader({
       )}
 
       <div className="flex shrink-0 items-center gap-1.5">
+        {onCompare && TERMINAL_PHASES.has(phase) && (
+          <ActionButton
+            label="Compare with…"
+            onClick={onCompare}
+            disabled={false}
+          />
+        )}
+
         {isRunning && (
           <>
             <ActionButton
@@ -175,20 +194,3 @@ function ActionButton({
   );
 }
 
-function formatDuration(ms: number): string {
-  if (ms < 1000) return `${ms}ms`;
-  const s = Math.floor(ms / 1000);
-  if (s < 60) return `${s}s`;
-  const m = Math.floor(s / 60);
-  const rem = s % 60;
-  if (m < 60) return rem > 0 ? `${m}m ${rem}s` : `${m}m`;
-  const h = Math.floor(m / 60);
-  const remM = m % 60;
-  return remM > 0 ? `${h}h ${remM}m` : `${h}h`;
-}
-
-function formatMicroUsd(micros: bigint): string {
-  const cents = Number(micros) / 10_000;
-  if (cents < 1) return `$${(Number(micros) / 1_000_000).toFixed(4)}`;
-  return `$${(Number(micros) / 1_000_000).toFixed(2)}`;
-}

package/src/workflow/WorkflowExecutionTaskPanel.tsx

@@ -4,6 +4,7 @@ import { memo } from "react";
 import { cn } from "@stigmer/theme";
 import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
 import type { DerivedTaskState } from "../internal/store/workflow-execution-event-store";
+import { formatDuration } from "./format-utils";
 
 /** Props for {@link WorkflowExecutionTaskPanel}. */
 export interface WorkflowExecutionTaskPanelProps {
@@ -126,10 +127,3 @@ export const WorkflowExecutionTaskPanel = memo(function WorkflowExecutionTaskPan
   );
 });
 
-function formatDuration(ms: number): string {
-  if (ms < 1000) return `${ms}ms`;
-  const s = ms / 1000;
-  if (s < 60) return `${s.toFixed(1)}s`;
-  const m = Math.floor(s / 60);
-  return `${m}m`;
-}

package/src/workflow/WorkflowExecutionTimeline.tsx

@@ -4,7 +4,7 @@ import { memo, useCallback, useEffect, useRef } from "react";
 import type { WorkflowExecutionEvent } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
 import { cn } from "@stigmer/theme";
 import { WorkflowExecutionTimelineEvent } from "./WorkflowExecutionTimelineEvent";
-import type { WorkflowEventStreamState } from "../internal/store/workflow-execution-event-store";
+import type { WorkflowEventStreamState, DerivedTaskState } from "../internal/store/workflow-execution-event-store";
 
 /** Props for {@link WorkflowExecutionTimeline}. */
 export interface WorkflowExecutionTimelineProps {
@@ -14,6 +14,17 @@ export interface WorkflowExecutionTimelineProps {
   readonly streamState: WorkflowEventStreamState;
   /** Callback when user clicks an agent execution link. */
   readonly onNavigateToAgentExecution?: (executionId: string) => void;
+  /** Derived task states for rendering interactive approval cards. */
+  readonly taskStates?: ReadonlyMap<string, DerivedTaskState>;
+  /** Callback to submit a human_input task approval decision. */
+  readonly onSubmitTaskApproval?: (
+    taskName: string,
+    outcome: string,
+    formData?: Record<string, unknown>,
+    comment?: string,
+  ) => Promise<unknown>;
+  /** True while a task approval submission is in flight. */
+  readonly isSubmittingApproval?: boolean;
   /** Additional CSS class names. */
   readonly className?: string;
 }
@@ -34,6 +45,9 @@ export const WorkflowExecutionTimeline = memo(function WorkflowExecutionTimeline
   events,
   streamState,
   onNavigateToAgentExecution,
+  taskStates,
+  onSubmitTaskApproval,
+  isSubmittingApproval,
   className,
 }: WorkflowExecutionTimelineProps) {
   const scrollRef = useRef<HTMLDivElement>(null);
@@ -77,9 +91,13 @@ export const WorkflowExecutionTimeline = memo(function WorkflowExecutionTimeline
   }
 
   if (events.length === 0 && isComplete) {
+    const hasTaskFallback = taskStates && taskStates.size > 0;
     return (
-      <div className={cn("flex flex-1 items-center justify-center text-sm text-muted-foreground", className)}>
-        No events recorded
+      <div className={cn("flex flex-1 flex-col items-center justify-center gap-1 text-sm text-muted-foreground", className)}>
+        <span>No events recorded</span>
+        {hasTaskFallback && (
+          <span className="text-xs">Task status available in the panel</span>
+        )}
       </div>
     );
   }
@@ -91,6 +109,9 @@ export const WorkflowExecutionTimeline = memo(function WorkflowExecutionTimeline
           key={event.eventId}
           event={event}
           onNavigateToAgentExecution={onNavigateToAgentExecution}
+          taskStates={taskStates}
+          onSubmitTaskApproval={onSubmitTaskApproval}
+          isSubmittingApproval={isSubmittingApproval}
         />
       ))}