@stigmer/react 3.12.1 → 3.12.3

package/src/workflow/useWorkflowCanvas.ts

@@ -7,6 +7,7 @@ import type {
   Edge,
   OnNodesChange,
   OnEdgesChange,
+  OnNodeDrag,
   Connection,
   IsValidConnection,
 } from "@xyflow/react";
@@ -67,6 +68,20 @@ import type { LayoutEngine } from "./layout/index.js";
 import { serializeSelection, pasteClipboard } from "./clipboard.js";
 import type { ClipboardEntry } from "./clipboard.js";
 
+/**
+ * Serializes a graph model to canonical YAML, or `null` if serialization
+ * fails. graphToYaml is total on models produced by yamlToGraph (its sort is
+ * cycle-protected and unknown kinds fall back to `unknown_N`), so `null` is
+ * a defensive outcome, not an expected one.
+ */
+function serializeGraphOrNull(model: WorkflowGraphModel): string | null {
+  try {
+    return graphToYaml(model);
+  } catch {
+    return null;
+  }
+}
+
 /** Selection state for the canvas inspector. */
 export interface CanvasSelection {
   readonly type: "node" | "edge";
@@ -90,6 +105,10 @@ export interface UseWorkflowCanvasReturn {
   readonly edges: Edge[];
   readonly onNodesChange: OnNodesChange;
   readonly onEdgesChange: OnEdgesChange;
+  /** Marks the model snapshot an in-flight drag started from. */
+  readonly onNodeDragStart: OnNodeDrag;
+  /** Records a completed node drag into the command history (oss#602). */
+  readonly onNodeDragStop: OnNodeDrag;
   readonly onConnect: (connection: Connection) => void;
   readonly isValidConnection: IsValidConnection;
   readonly onDrop: (event: React.DragEvent) => void;
@@ -175,6 +194,10 @@ export function useWorkflowCanvas(
   const [error, setError] = useState<string | null>(null);
   const [selection, setSelection] = useState<CanvasSelection | null>(null);
   const initialModelRef = useRef<WorkflowGraphModel | null>(null);
+  // Serialized form of the baseline model, kept in lockstep with
+  // initialModelRef. Dirty tracking compares serializations, not references —
+  // see the "Dirty tracking" section below for why.
+  const initialYamlRef = useRef<string | null>(null);
 
   const [nodes, setNodes, onNodesChangeRaw] = useNodesState([] as Node[]);
   const [edges, setEdges, onEdgesChangeRaw] = useEdgesState([] as Edge[]);
@@ -201,6 +224,7 @@ export function useWorkflowCanvas(
       setNodes([]);
       setEdges([]);
       initialModelRef.current = null;
+      initialYamlRef.current = null;
       return;
     }
 
@@ -209,6 +233,10 @@ export function useWorkflowCanvas(
       const laidOut = applyDagreLayout(parsed);
       history.reset(laidOut);
       initialModelRef.current = laidOut;
+      // Baseline is the canonical re-serialization, not the incoming string:
+      // dirty comparisons must be canonical-vs-canonical, immune to cosmetic
+      // formatting differences in host-provided YAML.
+      initialYamlRef.current = serializeGraphOrNull(laidOut);
       setError(null);
 
       const elements = toReactFlowElements(laidOut);
@@ -219,6 +247,7 @@ export function useWorkflowCanvas(
       setNodes([]);
       setEdges([]);
       initialModelRef.current = null;
+      initialYamlRef.current = null;
     }
   }, [yaml]);
 
@@ -252,6 +281,63 @@ export function useWorkflowCanvas(
     [onNodesChangeRaw],
   );
 
+  // During a drag, React Flow streams position changes into RF state only
+  // (via onNodesChange above); the model still holds the pre-drag
+  // positions. At drag stop, the completed gesture is recorded as ONE
+  // MoveNodesCommand — the auto-layout precedent — so drags survive
+  // later syncFromModel calls and are undoable (oss#602).
+  //
+  // The ref detects mid-drag model mutations: the keyboard undo listener
+  // and the host's YAML prop are both reachable while the mouse is down,
+  // and either one rebuilds the canvas from a model this drag never saw —
+  // recording the drag on top of that would fight the mutation.
+  const dragStartModelRef = useRef<WorkflowGraphModel | null>(null);
+
+  const onNodeDragStart: OnNodeDrag = useCallback(() => {
+    dragStartModelRef.current = history.currentModel;
+  }, [history.currentModel]);
+
+  const onNodeDragStop: OnNodeDrag = useCallback(
+    (_event, _node, draggedNodes) => {
+      const model = history.currentModel;
+      const startModel = dragStartModelRef.current;
+      dragStartModelRef.current = null;
+      if (!startModel || model !== startModel) return;
+
+      const oldPositions: { id: string; x: number; y: number }[] = [];
+      const newPositions: { id: string; x: number; y: number }[] = [];
+      for (const dragged of draggedNodes) {
+        const modelNode = model.nodes.find((n) => n.id === dragged.id);
+        if (!modelNode) continue;
+        oldPositions.push({
+          id: modelNode.id,
+          x: modelNode.position.x,
+          y: modelNode.position.y,
+        });
+        newPositions.push({
+          id: dragged.id,
+          x: dragged.position.x,
+          y: dragged.position.y,
+        });
+      }
+
+      const hasChanges = newPositions.some((np, i) => {
+        const op = oldPositions[i];
+        return Math.abs(op.x - np.x) > 0.5 || Math.abs(op.y - np.y) > 0.5;
+      });
+      if (!hasChanges) return;
+
+      // Record-only dispatch — deliberately NOT the syncing dispatch().
+      // React Flow already renders the dragged positions, so here the
+      // model catches up to the canvas (everywhere else the model leads
+      // and syncFromModel makes the canvas follow). Rebuilding the node
+      // array would be a visual no-op that wipes React Flow's `selected`
+      // flags at the end of every drag, breaking consecutive group drags.
+      history.dispatch(new MoveNodesCommand(oldPositions, newPositions));
+    },
+    [history.currentModel, history.dispatch],
+  );
+
   const onEdgesChange: OnEdgesChange = useCallback(
     (changes) => {
       onEdgesChangeRaw(changes);
@@ -387,6 +473,7 @@ export function useWorkflowCanvas(
         };
         history.reset(bootstrapModel);
         initialModelRef.current = bootstrapModel;
+        initialYamlRef.current = serializeGraphOrNull(bootstrapModel);
 
         const autoEdge = {
           id: generateEdgeId(),
@@ -1096,20 +1183,33 @@ export function useWorkflowCanvas(
   }, [history.redo, syncFromModel]);
 
   // ---------------------------------------------------------------------------
-  // Dirty tracking: model reference comparison
+  // Dirty tracking: serialization comparison (oss#609)
+  //
+  // Dirty means "saving would change the document". Node positions are not
+  // part of the serialized YAML (dagre recomputes them on every load), so a
+  // position-only edit session (drags, auto-layout) must NOT read as dirty:
+  // its save would round-trip byte-identical YAML, and because hosts reset
+  // the baseline by feeding saved YAML back through the `yaml` prop (whose
+  // re-parse effect is string-change gated), a reference-based flag could
+  // never clear afterwards — an armed Save button that saving cannot disarm.
+  // graphToYaml is total on parsed models (cycle-protected sort, unknown-kind
+  // fallback) and O(nodes+edges), cheap enough to compare per model change.
   // ---------------------------------------------------------------------------
 
   const graph = history.currentModel.nodes.length > 0 ? history.currentModel : null;
-  const isDirty = initialModelRef.current !== null && graph !== initialModelRef.current;
+  const currentYaml = useMemo(
+    () => (graph ? serializeGraphOrNull(graph) : null),
+    [graph],
+  );
+  // Reference comparison remains as the fallback for the defensive case where
+  // serialization failed (null); failing dirty-side keeps Save reachable.
+  const isDirty =
+    initialModelRef.current !== null &&
+    (currentYaml !== null && initialYamlRef.current !== null
+      ? currentYaml !== initialYamlRef.current
+      : graph !== initialModelRef.current);
 
-  const serializeToYaml = useCallback((): string | null => {
-    if (!graph) return null;
-    try {
-      return graphToYaml(graph);
-    } catch {
-      return null;
-    }
-  }, [graph]);
+  const serializeToYaml = useCallback((): string | null => currentYaml, [currentYaml]);
 
   return useMemo(
     () => ({
@@ -1117,6 +1217,8 @@ export function useWorkflowCanvas(
       edges,
       onNodesChange,
       onEdgesChange,
+      onNodeDragStart,
+      onNodeDragStop,
       onConnect,
       isValidConnection,
       onDrop,
@@ -1174,7 +1276,8 @@ export function useWorkflowCanvas(
       getSelectedNodeIds,
     }),
     [
-      nodes, edges, onNodesChange, onEdgesChange, onConnect,
+      nodes, edges, onNodesChange, onEdgesChange, onNodeDragStart,
+      onNodeDragStop, onConnect,
       isValidConnection, onDrop, onDragOver, onNodesDelete, onEdgesDelete,
       selection, selectNode, selectEdge, clearSelection, autoLayout,
       undo, redo, history.canUndo, history.canRedo, isDirty, graph, error,

package/src/workflow/useWorkflowExecutionPanel.ts

@@ -3,7 +3,7 @@
 // State + actions for the workflow execution viewer's WorkspaceSurface panel.
 // Domain: workflow (the lean analog of session/useSessionPanel).
 
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
 import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import {
@@ -50,7 +50,11 @@ export function workflowArtifactTabPath(artifact: Artifact): string {
 export interface WorkflowExecutionPanelController {
   /** The open-editor group store; subscribe with `useWorkspaceEditors`. */
   readonly editorsStore: WorkspaceEditorsStore;
-  /** Whether the panel is expanded or collapsed to the chip. */
+  /**
+   * Whether the panel is expanded or collapsed to the chip. In controlled
+   * mode ({@link UseWorkflowExecutionPanelOptions.open}) this mirrors the
+   * host's value.
+   */
   readonly isOpen: boolean;
   /** The active rail view id (an injected facet — `"artifacts"` today). */
   readonly view: string;
@@ -119,6 +123,38 @@ export interface UseWorkflowExecutionPanelOptions {
    * @default "artifacts"
    */
   readonly defaultView?: string;
+  /**
+   * Controlled open state. When provided, the host owns whether the panel is
+   * expanded: internal open intents (the chip toggle, Diagnose, an
+   * artifact/file-change/file open) no longer flip state themselves — they
+   * surface through {@link UseWorkflowExecutionPanelOptions.onOpenChange}
+   * and the panel follows this value. Leave `undefined` for the
+   * self-managing default. The same seam `useSessionPanel` carries (#651);
+   * kept domain-local, like the controllers themselves.
+   */
+  readonly open?: boolean;
+  /**
+   * Initial open state in uncontrolled mode. Ignored when
+   * {@link UseWorkflowExecutionPanelOptions.open} is provided.
+   *
+   * @default false
+   */
+  readonly defaultOpen?: boolean;
+  /**
+   * Called on every effective open/close transition — in BOTH modes,
+   * matching `useSessionPanel`'s convention (and departing from
+   * `useDetailTabs`'s DD-T05A-001 for the same principled reason): this
+   * panel opens ITSELF (`openDiagnosis`, `openArtifact`, `openFileChange`,
+   * `openFile` all expand a collapsed panel), and an embedding host that
+   * must react to those moments — widen a dock, make room for a diagnosis
+   * conversation — has no other seam. Passing only this callback observes
+   * the panel without controlling it.
+   *
+   * In controlled mode this fires once per open/close REQUEST (the host may
+   * decline by not updating `open` — a later identical request re-fires); in
+   * uncontrolled mode it fires once per actual transition.
+   */
+  readonly onOpenChange?: (open: boolean) => void;
 }
 
 /**
@@ -126,13 +162,59 @@ export interface UseWorkflowExecutionPanelOptions {
  */
 export function useWorkflowExecutionPanel({
   defaultView = "artifacts",
+  open,
+  defaultOpen = false,
+  onOpenChange,
 }: UseWorkflowExecutionPanelOptions = {}): WorkflowExecutionPanelController {
   const editorsStore = useWorkspaceEditorsStoreRef();
-  const [isOpen, setIsOpen] = useState(false);
+
+  // Uncontrolled-by-default / controlled-when-`open`-is-provided (React's own
+  // value/defaultValue convention — presence of the value prop decides, so an
+  // observe-only host can pass just `onOpenChange`). Same shape as
+  // `useSessionPanel`; re-transcribed rather than extracted because the
+  // controllers are deliberately not shared (see the interface doc above).
+  const isControlled = open !== undefined;
+  const [internalIsOpen, setInternalIsOpen] = useState(defaultOpen);
+  const isOpen = isControlled ? open : internalIsOpen;
+
+  // Latest-ref idiom: the host's callback and the mode/value mirrors live in
+  // refs so `requestOpenChange` — and every action callback built on it —
+  // stays referentially stable regardless of how the host authored
+  // `onOpenChange` (DD-010: an inline lambda must not churn the memoized
+  // controller and re-render the panel subtree).
+  const onOpenChangeRef = useRef(onOpenChange);
+  onOpenChangeRef.current = onOpenChange;
+  const isControlledRef = useRef(isControlled);
+  isControlledRef.current = isControlled;
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+
+  // The single seam every open/close intent routes through — the chip
+  // toggle, Diagnose, artifact/file-change/file opens, and the surface's
+  // collapse affordance. Uncontrolled: apply + notify (the ref is updated
+  // eagerly so two same-tick intents produce one notification). Controlled:
+  // notify only — the host owns the state, and the panel follows the `open`
+  // prop; the ref is NOT updated, so a declined request stays re-fireable.
+  const requestOpenChange = useCallback((next: boolean) => {
+    if (isOpenRef.current === next) return;
+    if (!isControlledRef.current) {
+      isOpenRef.current = next;
+      setInternalIsOpen(next);
+    }
+    onOpenChangeRef.current?.(next);
+  }, []);
+
   const [view, setViewState] = useState(defaultView);
 
-  const openPanel = useCallback(() => setIsOpen(true), []);
-  const closePanel = useCallback(() => setIsOpen(false), []);
+  const openPanel = useCallback(
+    () => requestOpenChange(true),
+    [requestOpenChange],
+  );
+
+  const closePanel = useCallback(
+    () => requestOpenChange(false),
+    [requestOpenChange],
+  );
 
   const setView = useCallback((viewId: string) => setViewState(viewId), []);
 
@@ -141,15 +223,15 @@ export function useWorkflowExecutionPanel({
       DIAGNOSIS_DOCUMENT_ENTRY_ID,
       DIAGNOSIS_DOCUMENT_PATH,
     );
-    setIsOpen(true);
-  }, [editorsStore]);
+    requestOpenChange(true);
+  }, [editorsStore, requestOpenChange]);
 
   const openFile = useCallback(
     (entryId: string, path: string, options?: OpenFileOptions) => {
       editorsStore.openPreview(entryId, path, options);
-      setIsOpen(true);
+      requestOpenChange(true);
     },
-    [editorsStore],
+    [editorsStore, requestOpenChange],
   );
 
   const openArtifact = useCallback(
@@ -158,9 +240,9 @@ export function useWorkflowExecutionPanel({
         ARTIFACT_DOCUMENT_ENTRY_ID,
         workflowArtifactTabPath(artifact),
       );
-      setIsOpen(true);
+      requestOpenChange(true);
     },
-    [editorsStore],
+    [editorsStore, requestOpenChange],
   );
 
   const pinArtifact = useCallback(
@@ -179,9 +261,9 @@ export function useWorkflowExecutionPanel({
         FILE_CHANGE_DOCUMENT_ENTRY_ID,
         fileChangeTabPath(change),
       );
-      setIsOpen(true);
+      requestOpenChange(true);
     },
-    [editorsStore],
+    [editorsStore, requestOpenChange],
   );
 
   const pinFileChange = useCallback(