@stonecrop/node-editor 0.13.12 → 0.14.0

package/dist/src/utils/stateTransforms.js

@@ -1,104 +1,148 @@
 import { Position } from '@vue-flow/core';
-export function statesToFlowElements(states, layout) {
-    const hasInputs = {};
-    const stateElements = [];
-    const stateHash = {};
-    let index = 0;
-    for (const [key, value] of Object.entries(states)) {
-        const el = {
-            id: key,
-            label: key,
-            position: layout?.[key]?.position ?? { x: 200 * index, y: 100 },
-            targetPosition: layout?.[key]?.targetPosition ?? Position.Left,
-            sourcePosition: layout?.[key]?.sourcePosition ?? Position.Right,
-        };
-        if (value.type === 'final') {
-            el.type = 'output';
-            el.class = 'default-output-node';
-        }
-        stateHash[key] = el;
-        index++;
-    }
-    for (const [key, value] of Object.entries(states)) {
-        if (value.on) {
-            for (const [edgeKey, edgeValue] of Object.entries(value.on)) {
-                const target = typeof edgeValue === 'string'
-                    ? edgeValue
-                    : edgeValue != null &&
-                        typeof edgeValue === 'object' &&
-                        'target' in edgeValue &&
-                        typeof edgeValue.target === 'string'
-                        ? edgeValue.target
-                        : '';
-                stateElements.push({
-                    id: `${key}-${target}`,
-                    source: key,
-                    target,
-                    label: edgeKey,
+export function statesToFlowElements(workflow, layout) {
+    const { states = [], actions = {} } = workflow;
+    const edges = [];
+    const nodes = [];
+    for (const [actionKey, actionDef] of Object.entries(actions)) {
+        // Stateless commands (print/email) have no graph presence; anything graph-owned needs states.
+        if (actionDef.stateless || !actionDef.allowedStates?.length)
+            continue;
+        // A self-transition (mutate-in-place `save`) renders as a self-loop on each allowed state:
+        // `source === target`, tagged `selfloop` so NodeEditor routes it to the arc renderer.
+        if (actionDef.selfTransition) {
+            for (const source of actionDef.allowedStates) {
+                edges.push({
+                    id: `${actionKey}-${source}`,
+                    source,
+                    target: source,
+                    label: actionDef.label ?? actionKey,
+                    data: { actionKey },
                     animated: true,
-                    type: 'smoothstep',
+                    type: 'selfloop',
                     interactionWidth: 40,
                 });
-                hasInputs[target] = true;
             }
+            continue;
         }
-    }
-    for (const [key] of Object.entries(stateHash)) {
-        if (!hasInputs[key]) {
-            stateHash[key].type = 'input';
-            stateHash[key].class = 'default-input-node';
+        // A cross-state transition needs a target; a malformed action with neither is skipped.
+        if (!actionDef.nextState)
+            continue;
+        for (const source of actionDef.allowedStates) {
+            edges.push({
+                id: `${actionKey}-${source}`,
+                source,
+                target: actionDef.nextState,
+                // The edge paints the human display label; its identity (the action key) rides in
+                // `data.actionKey`, so relabeling the edge renames the action without re-keying it.
+                label: actionDef.label ?? actionKey,
+                data: { actionKey },
+                animated: true,
+                type: 'smoothstep',
+                interactionWidth: 40,
+            });
         }
-        stateElements.push(stateHash[key]);
     }
-    return stateElements;
+    for (let index = 0; index < states.length; index++) {
+        const state = states[index];
+        const node = {
+            id: state,
+            label: state,
+            position: layout?.[state]?.position ?? { x: 200 * index, y: 100 },
+            targetPosition: layout?.[state]?.targetPosition ?? Position.Left,
+            sourcePosition: layout?.[state]?.sourcePosition ?? Position.Right,
+        };
+        // Every state renders identically — both handles, no start-state styling — so any transition
+        // (including a returning `reject`/`reopen` into the initial state) is authorable and a
+        // self-loop can anchor both ends. Marking an entry state is deferred (YAGNI) until needed.
+        nodes.push(node);
+    }
+    return [...edges, ...nodes];
 }
-export function flowElementsToStates(nextElements) {
-    const transitionsBySource = {};
+export function flowElementsToStates(nextElements, existingWorkflow) {
     const idToLabel = {};
-    const nodeTypeByLabel = {};
     const nextLayout = {};
-    // First pass: build id→label map from nodes so edge targets resolve correctly
+    const stateNames = [];
     for (const el of nextElements) {
-        if (!('source' in el)) {
-            idToLabel[el.id] = typeof el.label === 'string' ? el.label : el.id;
+        if ('source' in el)
+            continue;
+        const label = typeof el.label === 'string' ? el.label : el.id;
+        idToLabel[el.id] = label;
+        stateNames.push(label);
+        if (el.position) {
+            nextLayout[label] = {
+                position: el.position,
+                ...(el.targetPosition !== undefined && { targetPosition: el.targetPosition }),
+                ...(el.sourcePosition !== undefined && { sourcePosition: el.sourcePosition }),
+            };
         }
     }
-    // Second pass: collect node types, layout positions, and edge transitions
+    // Group directed edges by their stable action key. A round-tripped edge carries the key in
+    // `data.actionKey`; a freshly-drawn edge (no data yet) falls back to its label as the key — the
+    // one moment label and key coincide, when the action is first born. The edge's label is captured
+    // separately as the display name, so a later relabel renames the action without re-keying it.
+    const transitionGroups = {};
     for (const el of nextElements) {
-        if ('source' in el && 'target' in el) {
-            const edgeLabel = typeof el.label === 'string' ? el.label : el.id;
-            const sourceLabel = idToLabel[el.source] || el.source;
-            const targetLabel = idToLabel[el.target] || el.target;
-            transitionsBySource[sourceLabel] = transitionsBySource[sourceLabel] ?? {};
-            transitionsBySource[sourceLabel][edgeLabel] = { target: targetLabel };
+        if (!('source' in el))
+            continue;
+        const edgeLabel = typeof el.label === 'string' ? el.label : el.id;
+        const actionKey = el.data?.actionKey ?? edgeLabel;
+        const sourceLabel = idToLabel[el.source] || el.source;
+        const targetLabel = idToLabel[el.target] || el.target;
+        // Classify by topology, not by edge `type`: a self-loop (source === target) round-trips to a
+        // self-transition regardless of how it was authored (drawn node→itself, or re-rendered from a
+        // `selfTransition` action). A group's kind is set by its first edge; a multi-state self-loop
+        // (e.g. `save` on Draft AND Pending) accumulates each source into allowedStates.
+        const isSelf = el.source === el.target;
+        if (!transitionGroups[actionKey]) {
+            transitionGroups[actionKey] = {
+                allowedStates: [sourceLabel],
+                label: edgeLabel,
+                selfLoop: isSelf,
+                ...(isSelf ? {} : { nextState: targetLabel }),
+            };
         }
         else {
-            const nodeLabel = typeof el.label === 'string' ? el.label : el.id;
-            nodeTypeByLabel[nodeLabel] = el.type;
-            if (el.position) {
-                nextLayout[nodeLabel] = {
-                    position: el.position,
-                    ...(el.targetPosition !== undefined && { targetPosition: el.targetPosition }),
-                    ...(el.sourcePosition !== undefined && { sourcePosition: el.sourcePosition }),
-                };
-            }
+            transitionGroups[actionKey].allowedStates.push(sourceLabel);
         }
     }
-    // Build states from node types and collected transitions
-    const nextStates = {};
-    for (const [label, nodeType] of Object.entries(nodeTypeByLabel)) {
-        if (nodeType === 'output') {
-            nextStates[label] = { type: 'final' };
-        }
-        else {
-            nextStates[label] = { on: transitionsBySource[label] ?? {} };
-        }
+    const nextActions = {};
+    // Transitions (and self-transitions) derived from graph edges
+    for (const [actionKey, group] of Object.entries(transitionGroups)) {
+        const existing = existingWorkflow?.actions?.[actionKey];
+        nextActions[actionKey] = {
+            // Spread existing first so every field the graph does NOT own — clientHandler,
+            // requiredFields and any field added to ActionDefinition later — survives the
+            // round-trip. The graph owns topology (allowedStates/nextState/selfTransition) and the
+            // display label. (Enumerating named fields here previously dropped clientHandler.)
+            ...existing,
+            // The edge's label is the display name (decoupled from the key). Fall back to the
+            // existing label, then the key, if an edge ever arrives label-less.
+            label: group.label || existing?.label || actionKey,
+            // The graph owns topology only. A self-transition (self-loop) stays in place: mark
+            // `selfTransition`, carry NO `nextState`. A cross-state transition carries `nextState`
+            // and clears any stale self flag (a self-loop redrawn as a normal edge). Explicit
+            // `undefined` on the unused field is dropped by JSON.stringify, so no format churn.
+            allowedStates: group.allowedStates,
+            nextState: group.selfLoop ? undefined : group.nextState,
+            selfTransition: group.selfLoop ? true : undefined,
+        };
     }
-    // Capture any transition sources that had no corresponding node entry
-    for (const [sourceLabel, on] of Object.entries(transitionsBySource)) {
-        if (!nextStates[sourceLabel]) {
-            nextStates[sourceLabel] = { on };
+    // Pass through Verbs (stateless: true) and global Workflow actions (no allowedStates) verbatim
+    for (const [actionKey, actionDef] of Object.entries(existingWorkflow?.actions ?? {})) {
+        if (actionKey in transitionGroups)
+            continue;
+        if (actionDef.stateless || !actionDef.allowedStates?.length) {
+            nextActions[actionKey] = actionDef;
         }
+        // Workflow action with allowedStates not in graph = user deleted its edges → remove
     }
-    return { states: nextStates, layout: nextLayout };
+    return {
+        // Spread existingWorkflow first so every top-level key the graph does NOT own — the
+        // sibling `triggers` map (field-validation triggers), and any WorkflowMeta key added
+        // later — survives the round-trip. The graph owns topology only: states + actions,
+        // overridden below. (Same principle the per-action spread applies above; enumerating
+        // only states+actions here previously dropped `triggers` on every graph edit.)
+        workflow: { ...existingWorkflow, states: stateNames, actions: nextActions },
+        layout: nextLayout,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/node-editor",
-  "version": "0.13.12",
+  "version": "0.14.0",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -32,8 +32,9 @@
     "**/*.css"
   ],
   "dependencies": {
+    "@dagrejs/dagre": "^3.0.0",
     "@vue-flow/core": "^1.48.1",
-    "xstate": "^5.25.0"
+    "@stonecrop/schema": "0.14.0"
   },
   "peerDependencies": {
     "vue": "^3.5.33",
@@ -51,6 +52,7 @@
     "vitest": "^4.1.5",
     "vue": "^3.5.33",
     "vue-router": "^5.0.6",
+    "vue-tsc": "^3.3.6",
     "stonecrop-rig": "0.7.0"
   },
   "description": "Node editor UI for Stonecrop",
@@ -69,6 +71,7 @@
     "lint:fix": "oxlint --fix",
     "preview": "vite preview",
     "test": "vitest run --coverage.enabled false",
+    "test:types": "vue-tsc --noEmit",
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage"
   }

package/src/components/EditableEdge.vue

@@ -50,7 +50,7 @@ const showLabelInput = async () => {
 	newLabel.value = props.label
 	showInput.value = true
 	await nextTick()
-	inputRef.value.focus()
+	inputRef.value?.focus()
 }
 
 const submitNewLabel = () => {

package/src/components/NodeEditor.vue

@@ -16,6 +16,9 @@
 				<div>
 					<button class="button-default" @click="fitView">Center</button>
 				</div>
+				<div>
+					<button class="button-default" @click="autoArrange">Auto-arrange</button>
+				</div>
 				<div v-if="activeElementIndex > -1">
 					<button class="button-default" @click="shiftInput">Shift Input Position</button>
 				</div>
@@ -32,6 +35,7 @@
 			:prevent-scrolling="true"
 			:zoom-on-scroll="false"
 			:fit-view-on-init="true"
+			:pan-activation-key-code="null"
 			@connect="handleConnect"
 			@pane-ready="setInstance"
 			@node-click="handleNodeClick"
@@ -45,6 +49,9 @@
 			<template #edge-editable="props">
 				<EditableEdge v-bind="props" @change="labelChanged($event, props.id)" @remove="removeEdge(props.id)" />
 			</template>
+			<template #edge-selfloop="props">
+				<SelfLoopEdge v-bind="props" @change="labelChanged($event, props.id)" @remove="removeEdge(props.id)" />
+			</template>
 		</VueFlow>
 	</div>
 </template>
@@ -65,6 +72,8 @@ import { type HTMLAttributes, ref, computed, nextTick, onBeforeUnmount, onMounte
 
 import EditableEdge from './EditableEdge.vue'
 import EditableNode from './EditableNode.vue'
+import SelfLoopEdge from './SelfLoopEdge.vue'
+import { autoLayout } from '../utils/autoLayout'
 import type { FlowElements } from '../types'
 
 const { modelValue, nodeContainerClass = '' } = defineProps<{
@@ -86,9 +95,11 @@ const elements = computed({
 	get: () => {
 		const items = modelValue
 
-		// Add data to each element
+		// Add rendering flags without clobbering caller-provided data. Edges carry `data.actionKey`
+		// (the stable action identity from stateTransforms); wiping data here would drop it before it
+		// round-trips back through emitElements, silently re-keying actions on every graph edit.
 		for (const element of items) {
-			element.data = {}
+			element.data = { ...element.data }
 			if (element.type === 'input') {
 				element.data.hasInput = false
 				element.data.hasOutput = true
@@ -100,7 +111,10 @@ const elements = computed({
 				element.data.hasOutput = true
 			}
 			element.class = 'vue-flow__node-default'
-			element.type = 'editable'
+			// A self-loop edge (source === target) routes to the SelfLoopEdge arc renderer; everything
+			// else (nodes and cross-state edges) uses the default editable slot. getBezierPath draws a
+			// useless near-straight segment for a self-loop, so it must not fall through to 'editable'.
+			element.type = 'source' in element && element.source === element.target ? 'selfloop' : 'editable'
 		}
 
 		return items
@@ -173,6 +187,35 @@ const fitView = async () => {
 	await vueFlowInstance.value?.fitView()
 }
 
+const autoArrange = async () => {
+	// Read measured node sizes from the VueFlow store so the layout fits actual box widths (state
+	// labels differ in length); autoLayout falls back to default dimensions for any unmeasured node.
+	const store = vueFlowInstance.value
+	const dimensions: Record<string, { width: number; height: number }> = {}
+	for (const el of vueFlowElements.value) {
+		if ('source' in el) continue
+		const dims = store?.findNode?.(el.id)?.dimensions
+		if (dims?.width && dims?.height) dimensions[el.id] = { width: dims.width, height: dims.height }
+	}
+
+	const laid = autoLayout(vueFlowElements.value, { dimensions })
+	const positionById = new Map<string, { x: number; y: number }>()
+	for (const el of laid) {
+		if ('source' in el) continue
+		positionById.set(el.id, el.position)
+	}
+	// Apply positions onto the v-model elements — VueFlow reacts to these, same as shiftInput/Output.
+	for (const el of vueFlowElements.value) {
+		if ('source' in el) continue
+		const position = positionById.get(el.id)
+		if (position) el.position = position
+	}
+
+	emitElements()
+	await nextTick()
+	await fitView()
+}
+
 const addNode = () => {
 	let makeEdge = false
 	let newNodePosition = { x: Math.random() * 200, y: Math.random() * 200 }
@@ -234,11 +277,13 @@ const handleEdgeClick = ({ edge }: EdgeMouseEvent) => {
 
 const handleConnect = async (event: Connection) => {
 	const id = vueFlowElements.value.length
+	// A node connected to itself is a self-transition (mutate-in-place) — render it as a loop.
+	const isSelfLoop = event.source === event.target
 	const newEdge = {
 		id: `edge-${id}`,
 		source: event.source,
 		target: event.target,
-		type: 'editable',
+		type: isSelfLoop ? 'selfloop' : 'editable',
 		label: `New Edge`,
 		interactionWidth: 400,
 		animated: true,
@@ -283,17 +328,23 @@ const emitElements = () => {
 }
 
 .chart-controls {
-	padding-left: 20px;
-	padding-right: 20px;
-	height: 1.8em;
-	border-bottom: 1px solid #ccc;
+	position: absolute;
+	bottom: 0.5rem;
+	left: 0.5rem;
+	z-index: 10;
 	display: flex;
-	flex-direction: row;
-	justify-content: space-between;
+	flex-direction: column;
+	align-items: flex-start;
+	gap: 0.35rem;
+	padding: 0.4rem 0.5rem;
+	background: rgba(255, 255, 255, 0.92);
+	border: 1px solid #ccc;
+	border-radius: 4px;
+	box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12);
 }
 
 .chart-controls div {
-	margin-bottom: 5px;
+	margin-bottom: 0;
 }
 
 .defaultContainerClass {

package/src/components/SelfLoopEdge.vue

@@ -0,0 +1,88 @@
+<template>
+	<!-- transparent ghost path gives a ~20px click zone around the 2px visible stroke -->
+	<path :d="path.d" fill="none" stroke="transparent" stroke-width="20" class="vue-flow__edge-interaction" />
+	<path :id="id" :style="style" class="vue-flow__edge-path" :d="path.d" :marker-end="markerEnd" />
+
+	<EdgeLabelRenderer>
+		<div
+			:style="{
+				pointerEvents: 'all',
+				position: 'absolute',
+				transform: `translate(-50%, -50%) translate(${path.labelX}px,${path.labelY}px)`,
+			}"
+			class="nodrag nopan editable-edge-label"
+			@click="labelOnClick()"
+			@contextmenu.prevent="$emit('remove', id)">
+			<div class="vue-flow__edge-label">{{ label }}</div>
+			<div v-if="showInput" class="label-input-wrapper">
+				<input
+					ref="labelInput"
+					v-model="newLabel"
+					class="label-input"
+					@blur="showInput = false"
+					@keypress.enter="submitNewLabel" />
+			</div>
+		</div>
+	</EdgeLabelRenderer>
+</template>
+
+<script setup lang="ts">
+import { type EdgeProps, EdgeLabelRenderer } from '@vue-flow/core'
+import { computed, ref, nextTick, useTemplateRef } from 'vue'
+
+const props = defineProps<EdgeProps>()
+const emit = defineEmits(['change', 'remove'])
+
+// A self-loop connects a node's source handle to its own target handle. getBezierPath draws a nearly
+// straight segment across the node for that (the two handles are on the same box), so it's useless
+// here — we hand-author an arc that leaves the source handle, loops up and over the node top, and
+// returns to the target handle. LOOP_HEIGHT is how far above the handles the arc bulges.
+const LOOP_HEIGHT = 90
+const LOOP_SPREAD = 45
+
+const path = computed(() => {
+	const { sourceX, sourceY, targetX, targetY } = props
+	const d = `M ${sourceX},${sourceY} C ${sourceX + LOOP_SPREAD},${sourceY - LOOP_HEIGHT} ${
+		targetX - LOOP_SPREAD
+	},${targetY - LOOP_HEIGHT} ${targetX},${targetY}`
+	// Place the label near the arc's apex (a cubic bezier peaks around 0.75 of the control offset).
+	const labelX = (sourceX + targetX) / 2
+	const labelY = Math.min(sourceY, targetY) - LOOP_HEIGHT * 0.72
+	return { d, labelX, labelY }
+})
+
+const inputRef = useTemplateRef<HTMLInputElement>('labelInput')
+const newLabel = ref<EdgeProps['label']>('')
+const showInput = ref(false)
+let lastClick = 0
+
+const labelOnClick = async () => {
+	let now = Date.now()
+	if (now - lastClick < 500 && !showInput.value) {
+		await showLabelInput()
+	}
+	lastClick = now
+}
+
+const showLabelInput = async () => {
+	newLabel.value = props.label
+	showInput.value = true
+	await nextTick()
+	inputRef.value?.focus()
+}
+
+const submitNewLabel = () => {
+	showInput.value = false
+	emit('change', newLabel.value)
+}
+</script>
+
+<script lang="ts">
+export default {
+	inheritAttrs: false,
+}
+</script>
+
+<style>
+/* Label + input styles are shared with EditableEdge (defined there, global scope). */
+</style>

package/src/components/StateEditor.vue

@@ -6,12 +6,14 @@
 
 <script setup lang="ts">
 import { type HTMLAttributes, computed, onMounted } from 'vue'
+import type { WorkflowMeta } from '@stonecrop/schema'
 
 import NodeEditor from './NodeEditor.vue'
-import type { EditorStates, FlowElements, Layout } from '../types'
+import type { FlowElements, Layout } from '../types'
+import { autoLayout } from '../utils/autoLayout'
 import { statesToFlowElements, flowElementsToStates } from '../utils/stateTransforms'
 
-const states = defineModel<EditorStates>()
+const workflow = defineModel<WorkflowMeta>()
 const layout = defineModel<Layout>('layout')
 const { nodeContainerClass = '' } = defineProps<{
 	nodeContainerClass?: HTMLAttributes['class']
@@ -25,12 +27,17 @@ onMounted(() => {
 
 const elements = computed<FlowElements>({
 	get: () => {
-		if (!states.value) return []
-		return statesToFlowElements(states.value, layout.value)
+		if (!workflow.value) return []
+		const els = statesToFlowElements(workflow.value, layout.value)
+		// Seed an un-arranged workflow with an auto-computed dagre layout instead of the naive row.
+		// Ephemeral: these positions are persisted only once the author drags a node (which routes
+		// through flowElementsToStates → layout). A workflow with any saved layout keeps it as-is.
+		const noSavedLayout = !layout.value || Object.keys(layout.value).length === 0
+		return noSavedLayout ? autoLayout(els) : els
 	},
 	set: newValue => {
-		const { states: nextStates, layout: nextLayout } = flowElementsToStates(newValue)
-		states.value = nextStates
+		const { workflow: nextWorkflow, layout: nextLayout } = flowElementsToStates(newValue, workflow.value)
+		workflow.value = nextWorkflow
 		if (layout.value !== undefined) {
 			layout.value = nextLayout
 		}

package/src/types/index.ts

@@ -1,11 +1,4 @@
 import { type Elements, type Element, type XYPosition, Position } from '@vue-flow/core'
-import type { AnyStateNodeConfig } from 'xstate'
-
-/**
- * Editor states
- * @public
- */
-export type EditorStates = Record<string, AnyStateNodeConfig>
 
 /**
  * Flow elements
@@ -13,7 +6,9 @@ export type EditorStates = Record<string, AnyStateNodeConfig>
  */
 export type FlowElements = Elements<
 	{ hasInput?: boolean; hasOutput?: boolean },
-	{ hasInput?: boolean; hasOutput?: boolean }
+	// `actionKey` is the stable action identity carried on an edge, decoupled from its visible
+	// `label` (the display name). It lets an edge be relabeled without re-keying the action.
+	{ hasInput?: boolean; hasOutput?: boolean; actionKey?: string }
 >
 
 /**
@@ -22,7 +17,7 @@ export type FlowElements = Elements<
  */
 export type FlowElement = Element<
 	{ hasInput?: boolean; hasOutput?: boolean },
-	{ hasInput?: boolean; hasOutput?: boolean }
+	{ hasInput?: boolean; hasOutput?: boolean; actionKey?: string }
 >
 
 /**

package/src/utils/autoLayout.ts

@@ -0,0 +1,67 @@
+import { Graph, layout } from '@dagrejs/dagre'
+
+import type { FlowElements } from '../types'
+
+/**
+ * Options for {@link autoLayout}.
+ * @public
+ */
+export interface AutoLayoutOptions {
+	/** Layout direction. Defaults to `'LR'` to match the editor's Left/Right handle defaults. */
+	rankdir?: 'LR' | 'RL' | 'TB' | 'BT'
+	/** Fallback node width when no measured size is supplied (the seed path has no DOM to measure). */
+	nodeWidth?: number
+	/** Fallback node height when no measured size is supplied. */
+	nodeHeight?: number
+	/** Measured per-node sizes (node id → box) — supplied by the on-demand "Auto-arrange" button. */
+	dimensions?: Record<string, { width: number; height: number }>
+}
+
+/**
+ * Compute node positions for a workflow graph with dagre's layered (Sugiyama) algorithm.
+ *
+ * Pure and synchronous: takes VueFlow elements (nodes + edges) and returns a new elements array with
+ * each node's `position` replaced by a laid-out coordinate; edges and every other node field are
+ * passed through untouched. Used two ways — as the seed for an un-arranged workflow (fixed default
+ * dimensions, no DOM) and behind the toolbar button (measured `dimensions`).
+ *
+ * Self-loop edges (`source === target`) are skipped: dagre doesn't rank them, and they're reserved
+ * for the separate mutate-in-place self-transition feature.
+ * @public
+ */
+export function autoLayout(elements: FlowElements, options: AutoLayoutOptions = {}): FlowElements {
+	const { rankdir = 'LR', nodeWidth = 160, nodeHeight = 40, dimensions } = options
+	const sizeOf = (id: string) => dimensions?.[id] ?? { width: nodeWidth, height: nodeHeight }
+
+	// Nodes are the elements without a `source` (the same discriminator flowElementsToStates uses).
+	const nodeIds: string[] = []
+	for (const el of elements) {
+		if (!('source' in el)) nodeIds.push(el.id)
+	}
+	if (nodeIds.length === 0) return [...elements]
+
+	const graph = new Graph()
+	graph.setGraph({ rankdir, nodesep: 40, ranksep: 80, edgesep: 20 })
+	graph.setDefaultEdgeLabel(() => ({}))
+
+	for (const id of nodeIds) {
+		const { width, height } = sizeOf(id)
+		graph.setNode(id, { width, height })
+	}
+	for (const el of elements) {
+		if (!('source' in el)) continue
+		if (el.source === el.target) continue
+		graph.setEdge(el.source, el.target)
+	}
+
+	layout(graph)
+
+	// dagre reports each node by its CENTER; VueFlow positions nodes by their TOP-LEFT corner.
+	return elements.map(el => {
+		if ('source' in el) return el
+		const center = graph.node(el.id)
+		if (!center) return el
+		const { width, height } = sizeOf(el.id)
+		return { ...el, position: { x: center.x - width / 2, y: center.y - height / 2 } }
+	})
+}