@stigmer/react 0.5.0 → 1.0.0

package/src/workflow/WorkflowTopologyGraph.tsx

@@ -0,0 +1,250 @@
+"use client";
+
+import { memo, useMemo, useRef, useState, useCallback } from "react";
+import { cn } from "@stigmer/theme";
+import dagre from "@dagrejs/dagre";
+import type { TopologyNode, TopologyEdge, UseWorkflowTopologyReturn } from "./useWorkflowTopology";
+import { CATEGORY_COLORS, DAGRE_CONFIG, GRAPH_PADDING } from "./canvas-constants";
+
+/** Props for {@link WorkflowTopologyGraph}. */
+export interface WorkflowTopologyGraphProps {
+  /** Topology data from {@link useWorkflowTopology}. */
+  readonly topology: UseWorkflowTopologyReturn;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Read-only SVG DAG renderer for workflow topology.
+ *
+ * Uses dagre for layered layout computation and renders nodes as
+ * rounded rectangles with category-based coloring. Edges are drawn
+ * as SVG paths with arrowhead markers.
+ *
+ * Supports mouse wheel zoom and drag-to-pan for large workflows.
+ * All colors flow through `--stgm-*` tokens with sensible fallbacks.
+ *
+ * @since T10 (YAML Editor with Graph Preview)
+ */
+export const WorkflowTopologyGraph = memo(function WorkflowTopologyGraph({
+  topology,
+  className,
+}: WorkflowTopologyGraphProps) {
+  const { nodes, edges } = topology;
+  const svgRef = useRef<SVGSVGElement>(null);
+
+  const [transform, setTransform] = useState({ x: 0, y: 0, scale: 1 });
+  const dragState = useRef<{ startX: number; startY: number; startTx: number; startTy: number } | null>(null);
+
+  const layout = useMemo(() => {
+    if (nodes.length === 0) return null;
+    return computeLayout(nodes, edges);
+  }, [nodes, edges]);
+
+  const handleWheel = useCallback((e: React.WheelEvent) => {
+    e.preventDefault();
+    const factor = e.deltaY > 0 ? 0.9 : 1.1;
+    setTransform((prev) => ({
+      ...prev,
+      scale: Math.max(0.2, Math.min(3, prev.scale * factor)),
+    }));
+  }, []);
+
+  const handleMouseDown = useCallback((e: React.MouseEvent) => {
+    if (e.button !== 0) return;
+    dragState.current = {
+      startX: e.clientX,
+      startY: e.clientY,
+      startTx: transform.x,
+      startTy: transform.y,
+    };
+  }, [transform.x, transform.y]);
+
+  const handleMouseMove = useCallback((e: React.MouseEvent) => {
+    if (!dragState.current) return;
+    const dx = e.clientX - dragState.current.startX;
+    const dy = e.clientY - dragState.current.startY;
+    setTransform((prev) => ({
+      ...prev,
+      x: dragState.current!.startTx + dx,
+      y: dragState.current!.startTy + dy,
+    }));
+  }, []);
+
+  const handleMouseUp = useCallback(() => {
+    dragState.current = null;
+  }, []);
+
+  if (!layout || nodes.length === 0) {
+    return (
+      <div className={cn("flex items-center justify-center text-sm text-muted-foreground", className)}>
+        No tasks to visualize
+      </div>
+    );
+  }
+
+  const { layoutNodes, layoutEdges, width, height } = layout;
+
+  return (
+    <svg
+      ref={svgRef}
+      className={cn("h-full w-full cursor-grab select-none active:cursor-grabbing", className)}
+      viewBox={`0 0 ${width + GRAPH_PADDING * 2} ${height + GRAPH_PADDING * 2}`}
+      onWheel={handleWheel}
+      onMouseDown={handleMouseDown}
+      onMouseMove={handleMouseMove}
+      onMouseUp={handleMouseUp}
+      onMouseLeave={handleMouseUp}
+      role="img"
+      aria-label="Workflow topology graph"
+    >
+      <defs>
+        <marker
+          id="arrowhead"
+          markerWidth="8"
+          markerHeight="6"
+          refX="8"
+          refY="3"
+          orient="auto"
+        >
+          <polygon
+            points="0 0, 8 3, 0 6"
+            fill="var(--stgm-border, #d4d4d8)"
+          />
+        </marker>
+      </defs>
+
+      <g transform={`translate(${GRAPH_PADDING + transform.x}, ${GRAPH_PADDING + transform.y}) scale(${transform.scale})`}>
+        {layoutEdges.map((edge, i) => (
+          <EdgePath key={i} edge={edge} />
+        ))}
+
+        {layoutNodes.map((node) => (
+          <NodeRect key={node.id} node={node} />
+        ))}
+      </g>
+    </svg>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Layout computation with dagre
+// ---------------------------------------------------------------------------
+
+interface LayoutResult {
+  layoutNodes: TopologyNode[];
+  layoutEdges: LayoutEdge[];
+  width: number;
+  height: number;
+}
+
+interface LayoutEdge {
+  points: Array<{ x: number; y: number }>;
+  label?: string;
+}
+
+function computeLayout(
+  nodes: readonly TopologyNode[],
+  edges: readonly TopologyEdge[],
+): LayoutResult {
+  const g = new dagre.graphlib.Graph();
+  g.setGraph({ rankdir: DAGRE_CONFIG.rankdir, ranksep: DAGRE_CONFIG.ranksep, nodesep: DAGRE_CONFIG.nodesep });
+  g.setDefaultEdgeLabel(() => ({}));
+
+  for (const node of nodes) {
+    g.setNode(node.id, { width: node.width, height: node.height });
+  }
+
+  for (const edge of edges) {
+    g.setEdge(edge.source, edge.target, { label: edge.label });
+  }
+
+  dagre.layout(g);
+
+  const layoutNodes: TopologyNode[] = nodes.map((node) => {
+    const dagreNode = g.node(node.id);
+    return {
+      ...node,
+      x: dagreNode?.x ?? 0,
+      y: dagreNode?.y ?? 0,
+    };
+  });
+
+  const layoutEdges: LayoutEdge[] = edges.map((edge) => {
+    const dagreEdge = g.edge(edge.source, edge.target);
+    return {
+      points: dagreEdge?.points ?? [],
+      label: edge.label,
+    };
+  });
+
+  const graphMeta = g.graph();
+  const width = graphMeta?.width ?? 400;
+  const height = graphMeta?.height ?? 300;
+
+  return { layoutNodes, layoutEdges, width, height };
+}
+
+// ---------------------------------------------------------------------------
+// SVG sub-components
+// ---------------------------------------------------------------------------
+
+function NodeRect({ node }: { readonly node: TopologyNode }) {
+  const isTerminal = node.category === "start" || node.category === "end";
+  const fill = isTerminal
+    ? "var(--stgm-muted, #f5f5f5)"
+    : "var(--stgm-background, #fff)";
+  const stroke = CATEGORY_COLORS[node.category];
+  const rx = isTerminal ? node.height / 2 : 6;
+
+  return (
+    <g>
+      <rect
+        x={node.x - node.width / 2}
+        y={node.y - node.height / 2}
+        width={node.width}
+        height={node.height}
+        rx={rx}
+        ry={rx}
+        fill={fill}
+        stroke={stroke}
+        strokeWidth={isTerminal ? 1.5 : 2}
+      />
+      <text
+        x={node.x}
+        y={node.y}
+        textAnchor="middle"
+        dominantBaseline="central"
+        fontSize={isTerminal ? 11 : 12}
+        fontFamily="var(--stgm-font-sans, system-ui)"
+        fontWeight={isTerminal ? 400 : 500}
+        fill="var(--stgm-foreground, #1a1a2e)"
+      >
+        {truncateLabel(node.label, 20)}
+      </text>
+    </g>
+  );
+}
+
+function EdgePath({ edge }: { readonly edge: LayoutEdge }) {
+  if (edge.points.length < 2) return null;
+
+  const d = edge.points
+    .map((p, i) => `${i === 0 ? "M" : "L"} ${p.x} ${p.y}`)
+    .join(" ");
+
+  return (
+    <path
+      d={d}
+      fill="none"
+      stroke="var(--stgm-border, #d4d4d8)"
+      strokeWidth={1.5}
+      markerEnd="url(#arrowhead)"
+    />
+  );
+}
+
+function truncateLabel(label: string, maxLen: number): string {
+  if (label.length <= maxLen) return label;
+  return label.slice(0, maxLen - 1) + "\u2026";
+}

package/src/workflow/WorkflowYamlEditor.tsx

@@ -0,0 +1,271 @@
+"use client";
+
+import {
+  useRef,
+  useEffect,
+  memo,
+  type CSSProperties,
+} from "react";
+import { cn } from "@stigmer/theme";
+import { EditorState, Compartment } from "@codemirror/state";
+import { EditorView, keymap, lineNumbers, highlightActiveLine, drawSelection, highlightSpecialChars } from "@codemirror/view";
+import { yaml } from "@codemirror/lang-yaml";
+import { syntaxHighlighting, HighlightStyle, bracketMatching, indentOnInput, foldGutter } from "@codemirror/language";
+import { tags } from "@lezer/highlight";
+import { lintGutter, type Diagnostic, setDiagnostics } from "@codemirror/lint";
+import { defaultKeymap, indentWithTab, history, historyKeymap } from "@codemirror/commands";
+import { autocompletion } from "@codemirror/autocomplete";
+
+/** Props for {@link WorkflowYamlEditor}. */
+export interface WorkflowYamlEditorProps {
+  /** Current YAML content. */
+  readonly value: string;
+  /** Called when the editor content changes. */
+  readonly onChange?: (value: string) => void;
+  /** Validation diagnostics to display as inline markers. */
+  readonly diagnostics?: readonly Diagnostic[];
+  /** Whether the editor is read-only. @default false */
+  readonly readOnly?: boolean;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+  /** Additional inline styles for the root container. */
+  readonly style?: CSSProperties;
+}
+
+/**
+ * Schema-aware YAML editor built on CodeMirror 6.
+ *
+ * Provides syntax highlighting, line numbers, bracket matching,
+ * code folding, undo/redo, and inline diagnostic markers driven by
+ * external validation (via the `diagnostics` prop).
+ *
+ * Themed via `--stgm-*` CSS custom properties to respect the host
+ * application's design tokens.
+ *
+ * This is an optional SDK component — it requires CodeMirror peer
+ * dependencies which are tree-shaken when not imported (DD-013).
+ *
+ * @example
+ * ```tsx
+ * <WorkflowYamlEditor
+ *   value={yaml}
+ *   onChange={setYaml}
+ *   diagnostics={diagnostics}
+ * />
+ * ```
+ *
+ * @since T10 (YAML Editor with Graph Preview)
+ */
+export const WorkflowYamlEditor = memo(function WorkflowYamlEditor({
+  value,
+  onChange,
+  diagnostics,
+  readOnly = false,
+  className,
+  style,
+}: WorkflowYamlEditorProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const viewRef = useRef<EditorView | null>(null);
+  const readOnlyCompartment = useRef(new Compartment());
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  const isInternalUpdate = useRef(false);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const updateListener = EditorView.updateListener.of((update) => {
+      if (update.docChanged) {
+        isInternalUpdate.current = true;
+        onChangeRef.current?.(update.state.doc.toString());
+      }
+    });
+
+    const state = EditorState.create({
+      doc: value,
+      extensions: [
+        lineNumbers(),
+        highlightActiveLine(),
+        highlightSpecialChars(),
+        drawSelection(),
+        bracketMatching(),
+        indentOnInput(),
+        foldGutter(),
+        history(),
+        yaml(),
+        syntaxHighlighting(stigmerHighlightStyle, { fallback: true }),
+        autocompletion(),
+        lintGutter(),
+        keymap.of([...defaultKeymap, ...historyKeymap, indentWithTab]),
+        readOnlyCompartment.current.of(EditorState.readOnly.of(readOnly)),
+        stigmerTheme,
+        updateListener,
+      ],
+    });
+
+    const view = new EditorView({
+      state,
+      parent: containerRef.current,
+    });
+
+    viewRef.current = view;
+
+    return () => {
+      view.destroy();
+      viewRef.current = null;
+    };
+  }, []);
+
+  // Sync external value changes into the editor
+  useEffect(() => {
+    const view = viewRef.current;
+    if (!view) return;
+
+    if (isInternalUpdate.current) {
+      isInternalUpdate.current = false;
+      return;
+    }
+
+    const currentDoc = view.state.doc.toString();
+    if (currentDoc !== value) {
+      view.dispatch({
+        changes: {
+          from: 0,
+          to: currentDoc.length,
+          insert: value,
+        },
+      });
+    }
+  }, [value]);
+
+  useEffect(() => {
+    const view = viewRef.current;
+    if (!view) return;
+
+    view.dispatch({
+      effects: readOnlyCompartment.current.reconfigure(
+        EditorState.readOnly.of(readOnly),
+      ),
+    });
+  }, [readOnly]);
+
+  // Sync diagnostics into CodeMirror's lint system
+  useEffect(() => {
+    const view = viewRef.current;
+    if (!view) return;
+
+    const cmDiags: Diagnostic[] = diagnostics
+      ? diagnostics.map((d) => ({
+          ...d,
+          from: Math.min(d.from, view.state.doc.length),
+          to: Math.min(d.to, view.state.doc.length),
+        }))
+      : [];
+
+    view.dispatch(setDiagnostics(view.state, cmDiags));
+  }, [diagnostics]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn(
+        "stgm-yaml-editor overflow-auto rounded-md border border-border bg-background font-mono text-sm",
+        className,
+      )}
+      style={style}
+    />
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Syntax highlighting: maps lezer tags to --stgm-syntax-* CSS variables
+// ---------------------------------------------------------------------------
+
+const stigmerHighlightStyle = HighlightStyle.define([
+  { tag: tags.propertyName, color: "var(--stgm-syntax-property, #0550ae)" },
+  { tag: tags.tagName, color: "var(--stgm-syntax-tag, #cf222e)" },
+  { tag: tags.keyword, color: "var(--stgm-syntax-keyword, #8250df)", fontWeight: "bold" },
+  { tag: tags.string, color: "var(--stgm-syntax-string, #0a3069)" },
+  { tag: tags.number, color: "var(--stgm-syntax-number, #953800)" },
+  { tag: [tags.bool, tags.null], color: "var(--stgm-syntax-bool, #8250df)" },
+  { tag: tags.atom, color: "var(--stgm-syntax-atom, #cf222e)" },
+  { tag: tags.comment, color: "var(--stgm-syntax-comment, #6e7781)", fontStyle: "italic" },
+  { tag: tags.meta, color: "var(--stgm-syntax-meta, #8250df)" },
+  { tag: tags.name, color: "var(--stgm-foreground, #1a1a2e)" },
+  { tag: tags.definition(tags.name), color: "var(--stgm-syntax-property, #0550ae)" },
+  { tag: tags.separator, color: "var(--stgm-muted-foreground, #737373)" },
+  { tag: tags.punctuation, color: "var(--stgm-muted-foreground, #737373)" },
+]);
+
+// ---------------------------------------------------------------------------
+// CodeMirror theme bridge: maps --stgm-* tokens to editor styles
+// ---------------------------------------------------------------------------
+
+const stigmerTheme = EditorView.theme({
+  "&": {
+    height: "100%",
+    backgroundColor: "var(--stgm-background, #fff)",
+    color: "var(--stgm-foreground, #1a1a2e)",
+    fontSize: "13px",
+  },
+  ".cm-content": {
+    caretColor: "var(--stgm-foreground, #1a1a2e)",
+    fontFamily: "var(--stgm-font-mono, ui-monospace, monospace)",
+    padding: "8px 0",
+  },
+  ".cm-cursor, .cm-dropCursor": {
+    borderLeftColor: "var(--stgm-foreground, #1a1a2e)",
+  },
+  "&.cm-focused .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection":
+    {
+      backgroundColor: "var(--stgm-accent, #e0e7ff)",
+    },
+  ".cm-gutters": {
+    backgroundColor: "var(--stgm-muted, #f5f5f5)",
+    color: "var(--stgm-muted-foreground, #737373)",
+    border: "none",
+    borderRight: "1px solid var(--stgm-border, #e5e5e5)",
+  },
+  ".cm-activeLineGutter": {
+    backgroundColor: "var(--stgm-accent, #e0e7ff)",
+  },
+  ".cm-activeLine": {
+    backgroundColor: "color-mix(in srgb, var(--stgm-accent, #e0e7ff) 30%, transparent)",
+  },
+  ".cm-foldPlaceholder": {
+    backgroundColor: "var(--stgm-muted, #f5f5f5)",
+    border: "1px solid var(--stgm-border, #e5e5e5)",
+    color: "var(--stgm-muted-foreground, #737373)",
+  },
+  ".cm-tooltip": {
+    backgroundColor: "var(--stgm-popover, #fff)",
+    color: "var(--stgm-popover-foreground, #1a1a2e)",
+    border: "1px solid var(--stgm-border, #e5e5e5)",
+    borderRadius: "6px",
+    boxShadow: "0 2px 8px rgba(0,0,0,0.08)",
+  },
+  ".cm-tooltip-autocomplete": {
+    "& > ul > li[aria-selected]": {
+      backgroundColor: "var(--stgm-accent, #e0e7ff)",
+      color: "var(--stgm-accent-foreground, #1a1a2e)",
+    },
+  },
+  ".cm-diagnostic-error": {
+    borderLeft: "3px solid var(--stgm-destructive, #ef4444)",
+  },
+  ".cm-diagnostic-warning": {
+    borderLeft: "3px solid var(--stgm-warning, #f59e0b)",
+  },
+  ".cm-diagnostic-info": {
+    borderLeft: "3px solid var(--stgm-primary, #6366f1)",
+  },
+  ".cm-lint-marker-error": {
+    content: "'●'",
+    color: "var(--stgm-destructive, #ef4444)",
+  },
+  ".cm-lint-marker-warning": {
+    content: "'●'",
+    color: "var(--stgm-warning, #f59e0b)",
+  },
+});

package/src/workflow/__tests__/starter-workflow-yaml.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { STARTER_WORKFLOW_YAML } from "../starter-workflow-yaml";
+import { yamlToGraph, graphToYaml } from "../workflow-graph-conversions";
+import { parseWorkflowYaml } from "../serialize-workflow-yaml";
+import { START_NODE_ID, END_NODE_ID } from "../workflow-graph-model";
+
+describe("STARTER_WORKFLOW_YAML", () => {
+  it("parses via yamlToGraph without throwing", () => {
+    const graph = yamlToGraph(STARTER_WORKFLOW_YAML);
+
+    expect(graph.document.namespace).toBe("default");
+    expect(graph.document.name).toBe("my-workflow");
+    expect(graph.document.version).toBe("0.1.0");
+    expect(graph.document.dsl).toBe("1.0.0");
+    expect(graph.description).toBe("A new workflow");
+
+    const taskNodes = graph.nodes.filter(
+      (n) => n.id !== START_NODE_ID && n.id !== END_NODE_ID,
+    );
+    expect(taskNodes).toHaveLength(1);
+    expect(taskNodes[0].taskName).toBe("step_1");
+  });
+
+  it("parses via parseWorkflowYaml without throwing", () => {
+    const input = parseWorkflowYaml(STARTER_WORKFLOW_YAML, "test-org");
+
+    expect(input.name).toBe("my-workflow");
+    expect(input.org).toBe("test-org");
+    expect(input.document?.namespace).toBe("default");
+    expect(input.document?.name).toBe("my-workflow");
+    expect(input.document?.version).toBe("0.1.0");
+    expect(input.tasks).toBeDefined();
+    expect(input.tasks).toHaveLength(1);
+    expect(input.tasks![0].name).toBe("step_1");
+  });
+
+  it("round-trips through graphToYaml -> yamlToGraph", () => {
+    const original = yamlToGraph(STARTER_WORKFLOW_YAML);
+    const serialized = graphToYaml(original);
+    const roundTripped = yamlToGraph(serialized);
+
+    expect(roundTripped.document.namespace).toBe(original.document.namespace);
+    expect(roundTripped.document.name).toBe(original.document.name);
+    expect(roundTripped.document.version).toBe(original.document.version);
+    expect(roundTripped.document.dsl).toBe(original.document.dsl);
+
+    const originalTasks = original.nodes.filter(
+      (n) => n.id !== START_NODE_ID && n.id !== END_NODE_ID,
+    );
+    const roundTrippedTasks = roundTripped.nodes.filter(
+      (n) => n.id !== START_NODE_ID && n.id !== END_NODE_ID,
+    );
+    expect(roundTrippedTasks).toHaveLength(originalTasks.length);
+    expect(roundTrippedTasks[0].taskName).toBe(originalTasks[0].taskName);
+    expect(roundTrippedTasks[0].kind).toBe(originalTasks[0].kind);
+  });
+});

package/src/workflow/canvas-constants.ts

@@ -0,0 +1,87 @@
+import type { TopologyNodeCategory } from "./useWorkflowTopology";
+import type { TaskKindCategory } from "./types";
+
+/**
+ * Category-to-color mapping using `--stgm-*` CSS custom properties.
+ *
+ * Shared between the read-only SVG topology graph and the interactive
+ * React Flow canvas editor to ensure consistent visual language.
+ */
+export const CATEGORY_COLORS: Readonly<Record<TopologyNodeCategory, string>> = {
+  start: "var(--stgm-muted-foreground, #737373)",
+  end: "var(--stgm-muted-foreground, #737373)",
+  ai: "var(--stgm-chart-purple, #8b5cf6)",
+  control_flow: "var(--stgm-chart-blue, #3b82f6)",
+  invocation: "var(--stgm-muted-foreground, #737373)",
+  data: "var(--stgm-chart-green, #22c55e)",
+  governance: "var(--stgm-chart-orange, #f97316)",
+  event: "var(--stgm-chart-yellow, #eab308)",
+  unspecified: "var(--stgm-muted-foreground, #737373)",
+};
+
+/** Dagre layout configuration for top-to-bottom DAG rendering. */
+export const DAGRE_CONFIG = {
+  rankdir: "TB" as const,
+  ranksep: 60,
+  nodesep: 30,
+} as const;
+
+/** Default padding around the SVG viewBox in the read-only graph. */
+export const GRAPH_PADDING = 40;
+
+/** Node dimensions for the read-only topology graph. */
+export const TOPOLOGY_NODE_WIDTH = 180;
+export const TOPOLOGY_NODE_HEIGHT = 40;
+
+/** Node dimensions for canvas task nodes (wider to accommodate controls). */
+export const CANVAS_NODE_WIDTH = 220;
+export const CANVAS_NODE_HEIGHT = 56;
+
+/** Sentinel node dimensions (Start/End pills). */
+export const SENTINEL_NODE_WIDTH = 100;
+export const SENTINEL_NODE_HEIGHT = 36;
+
+/** React Flow handle (port) positions for canvas nodes. */
+export const HANDLE_POSITIONS = {
+  input: { x: 0.5, y: 0 },
+  output: { x: 0.5, y: 1 },
+} as const;
+
+/** Human-readable display names for task kind categories. */
+export const CATEGORY_DISPLAY_NAMES: Readonly<Record<TaskKindCategory, string>> = {
+  ai: "AI",
+  control_flow: "Control Flow",
+  invocation: "Invocation",
+  data: "Data",
+  governance: "Governance",
+  event: "Event",
+  unspecified: "Other",
+};
+
+/**
+ * Identifier pattern for workflow task names.
+ *
+ * Mirrors the `buf.validate` constraint on `WorkflowTask.name` in
+ * `ai/stigmer/agentic/workflow/v1/spec.proto`.
+ */
+export const TASK_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/** User-facing error message when a task name fails {@link TASK_NAME_PATTERN}. */
+export const TASK_NAME_PATTERN_ERROR =
+  "Must start with a letter or underscore, alphanumeric/underscore only";
+
+/**
+ * Rendering order for task kind categories in palettes and pickers.
+ *
+ * AI tasks first (most common), then control flow, invocation, data,
+ * governance, events. Unspecified is a catch-all at the end.
+ */
+export const CATEGORY_ORDER: readonly TaskKindCategory[] = [
+  "ai",
+  "control_flow",
+  "invocation",
+  "data",
+  "governance",
+  "event",
+  "unspecified",
+];

package/src/workflow/canvas-icons.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+/**
+ * Shared 14×14 inline SVG icons for the workflow canvas editor.
+ *
+ * Used by {@link CanvasTaskNode} (hover buttons + NodeToolbar) and
+ * {@link CanvasContextMenu} to maintain visual consistency across
+ * all node action surfaces.
+ *
+ * @internal Not exported from the SDK barrel — implementation detail.
+ */
+
+export function TrashIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" aria-hidden="true">
+      <path d="M3 4h8M5 4V3a1 1 0 0 1 1-1h2a1 1 0 0 1 1 1v1M5.5 6.5v3.5M8.5 6.5v3.5M4 4l.5 7.5a.5.5 0 0 0 .5.5h4a.5.5 0 0 0 .5-.5L10 4" />
+    </svg>
+  );
+}
+
+export function DuplicateIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <rect x="5" y="5" width="7" height="7" rx="1" />
+      <path d="M9 5V3a1 1 0 0 0-1-1H3a1 1 0 0 0-1 1v5a1 1 0 0 0 1 1h2" />
+    </svg>
+  );
+}
+
+export function PlusIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" aria-hidden="true">
+      <path d="M7 3v8M3 7h8" />
+    </svg>
+  );
+}