@stigmer/react 3.12.0 → 3.12.2

package/src/workflow/useWorkflowCanvas.ts

@@ -1,13 +1,13 @@
 "use client";
 
 import { useState, useCallback, useMemo, useRef, useEffect } from "react";
-import type { RefObject } from "react";
 import { useNodesState, useEdgesState, useReactFlow } from "@xyflow/react";
 import type {
   Node,
   Edge,
   OnNodesChange,
   OnEdgesChange,
+  OnNodeDrag,
   Connection,
   IsValidConnection,
 } from "@xyflow/react";
@@ -68,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";
@@ -91,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;
@@ -165,19 +183,21 @@ export interface UseWorkflowCanvasReturn {
  * is derived from the model after each mutation.
  *
  * @param yaml - The workflow YAML to initialize from. Changes trigger re-parse.
- * @param containerRef - Ref to the canvas container for keyboard shortcut scoping.
  * @param options - Optional configuration including a custom layout engine.
  *
  * @since T15 (Visual Canvas Editor)
  */
 export function useWorkflowCanvas(
   yaml: string | null,
-  containerRef: RefObject<HTMLDivElement | null>,
   options?: UseWorkflowCanvasOptions,
 ): UseWorkflowCanvasReturn {
   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[]);
@@ -195,7 +215,7 @@ export function useWorkflowCanvas(
   }, [yaml]);
 
   // Set up graph history with the parsed model
-  const history = useGraphHistory(parsedModel, containerRef);
+  const history = useGraphHistory(parsedModel);
 
   // Sync: when YAML changes, reset the history and RF elements
   useEffect(() => {
@@ -204,6 +224,7 @@ export function useWorkflowCanvas(
       setNodes([]);
       setEdges([]);
       initialModelRef.current = null;
+      initialYamlRef.current = null;
       return;
     }
 
@@ -212,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);
@@ -222,6 +247,7 @@ export function useWorkflowCanvas(
       setNodes([]);
       setEdges([]);
       initialModelRef.current = null;
+      initialYamlRef.current = null;
     }
   }, [yaml]);
 
@@ -255,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);
@@ -390,6 +473,7 @@ export function useWorkflowCanvas(
         };
         history.reset(bootstrapModel);
         initialModelRef.current = bootstrapModel;
+        initialYamlRef.current = serializeGraphOrNull(bootstrapModel);
 
         const autoEdge = {
           id: generateEdgeId(),
@@ -1083,31 +1167,49 @@ export function useWorkflowCanvas(
   // Undo / Redo (delegates to history, then syncs RF)
   // ---------------------------------------------------------------------------
 
+  // Sync from the model RETURNED by the mutation, mirroring dispatch().
+  // `history.currentModel` is a render-time snapshot — reading it here
+  // after undo()/redo() yields the PRE-mutation model (oss#588: the
+  // canvas re-rendered the still-deleted graph while the inspector,
+  // reading state on the next render, showed the restored node).
   const undo = useCallback(() => {
-    history.undo();
-    syncFromModel(history.currentModel);
-  }, [history, syncFromModel]);
+    const next = history.undo();
+    if (next) syncFromModel(next);
+  }, [history.undo, syncFromModel]);
 
   const redo = useCallback(() => {
-    history.redo();
-    syncFromModel(history.currentModel);
-  }, [history, syncFromModel]);
+    const next = history.redo();
+    if (next) syncFromModel(next);
+  }, [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(
     () => ({
@@ -1115,6 +1217,8 @@ export function useWorkflowCanvas(
       edges,
       onNodesChange,
       onEdgesChange,
+      onNodeDragStart,
+      onNodeDragStop,
       onConnect,
       isValidConnection,
       onDrop,
@@ -1172,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(

package/src/workflow/useWorkflowSave.ts

@@ -2,6 +2,7 @@
 
 import { useCallback, useMemo, useRef, useState } from "react";
 import { useStigmer } from "../hooks.js";
+import { isUnimplemented } from "../internal/isUnimplemented.js";
 import { parseWorkflowYaml } from "./serialize-workflow-yaml.js";
 
 /** Options for a single save invocation. */
@@ -57,7 +58,7 @@ export function useWorkflowSave(org: string): UseWorkflowSaveReturn {
         const wrapped =
           err instanceof Error ? err : new Error(String(err));
 
-        if (isUnimplementedError(err)) {
+        if (isUnimplemented(err)) {
           setError(
             new Error(
               "Workflow save is not yet available on this server. " +
@@ -77,17 +78,3 @@ export function useWorkflowSave(org: string): UseWorkflowSaveReturn {
 
   return useMemo(() => ({ save, isSaving, error }), [save, isSaving, error]);
 }
-
-/**
- * Detect gRPC UNIMPLEMENTED (code 12) from a Connect error or
- * a StigmerError wrapping one. The SDK's CODE_MAP doesn't include
- * Unimplemented so it surfaces as "unknown" — check connectCode.
- */
-function isUnimplementedError(err: unknown): boolean {
-  if (!err || typeof err !== "object") return false;
-  if ("connectCode" in err && (err as { connectCode: number }).connectCode === 12) {
-    return true;
-  }
-  const msg = (err as { message?: string }).message ?? "";
-  return msg.includes("[unimplemented]") || msg.includes("UNIMPLEMENTED");
-}

package/src/workflow/workflow-graph-conversions.ts

@@ -58,6 +58,22 @@ export function taskKindToString(kind: WorkflowTaskKind): string {
   return TASK_KIND_STRINGS.get(kind) ?? `unknown_${kind}`;
 }
 
+/**
+ * Canonical kind key for a graph node.
+ *
+ * Task nodes resolve to their `WorkflowTaskKind` enum name; the start/end
+ * sentinels resolve to their pseudo-kind (`__start__` / `__end__`), which
+ * doubles as their node id and their key in the visual registry. Sentinels
+ * carry enum value 0, which `taskKindToString` would render as its internal
+ * `unknown_*` fallback — routing them through here keeps that fallback out
+ * of every user-visible surface (oss#581).
+ */
+export function graphNodeKindString(node: WorkflowGraphNode): string {
+  return node.id === START_NODE_ID || node.id === END_NODE_ID
+    ? node.id
+    : taskKindToString(node.kind);
+}
+
 export function stringToTaskKind(str: string): WorkflowTaskKind {
   return STRING_TO_TASK_KIND.get(str) ?? WorkflowTaskKind.workflow_task_kind_unspecified;
 }
@@ -148,7 +164,6 @@ export function yamlToGraph(yaml: string): WorkflowGraphModel {
   for (const task of tasks) {
     const config = (task.task_config ?? task.taskConfig ?? {}) as JsonObject;
     const kindEnum = stringToTaskKind(task.kind);
-    const kindStr = kindEnum !== WorkflowTaskKind.workflow_task_kind_unspecified ? task.kind : task.kind;
 
     nodes.push({
       id: task.name,
@@ -469,6 +484,13 @@ export interface NodeExecutionState {
 export interface CanvasTaskNodeData extends Record<string, unknown> {
   taskName: string;
   kind: WorkflowTaskKind;
+  /**
+   * Canonical kind key (see {@link graphNodeKindString}): the
+   * `WorkflowTaskKind` enum name for task nodes, or the `__start__` /
+   * `__end__` pseudo-kind for sentinels — never `taskKindToString`'s
+   * internal `unknown_*` fallback. Rendered as the `data-task-kind` DOM
+   * attribute on task nodes only; sentinels omit that attribute.
+   */
   kindString: string;
   category: TopologyNodeCategory;
   visualClass: VisualClass;
@@ -511,8 +533,8 @@ export function toReactFlowElements(graph: WorkflowGraphModel): {
 } {
   const nodes: Node[] = graph.nodes.map((node) => {
     const isSentinel = node.id === START_NODE_ID || node.id === END_NODE_ID;
-    const kindString = taskKindToString(node.kind);
-    const visualSpec = getVisualSpec(isSentinel ? node.id : kindString);
+    const kindString = graphNodeKindString(node);
+    const visualSpec = getVisualSpec(kindString);
     return {
       id: node.id,
       type: CANVAS_TASK_NODE_TYPE,