From 96913d2738b0a3908e96a699c59ad6a03eb15565 Mon Sep 17 00:00:00 2001
From: milanofthe <milanofthe@users.noreply.github.com>
Date: Sun, 13 Sep 2026 17:55:15 +0200
Subject: [PATCH] Add labels to connections with inline editing

---
 docs/pvm-spec.md                              |   1 +
 src/lib/components/canvas/flowConverters.ts   |   2 +-
 src/lib/components/contextMenuBuilders.ts     |   6 +
 .../components/edges/OrthogonalEdge.svelte    | 146 +++++++++++++++++-
 src/lib/constants/dimensions.ts               |  10 ++
 src/lib/stores/clipboard.ts                   |   3 +-
 src/lib/stores/edgeLabelEdit.svelte.ts        |  10 ++
 src/lib/stores/graph/connections.ts           |  16 ++
 src/lib/stores/graph/index.ts                 |   1 +
 src/lib/stores/graph/nodes.ts                 |   3 +-
 src/lib/types/nodes.ts                        |   1 +
 11 files changed, 195 insertions(+), 4 deletions(-)
 create mode 100644 src/lib/stores/edgeLabelEdit.svelte.ts

diff --git a/docs/pvm-spec.md b/docs/pvm-spec.md
index e74711e1..db717de4 100644
--- a/docs/pvm-spec.md
+++ b/docs/pvm-spec.md
@@ -192,6 +192,7 @@ A connection is a directed wire from a source output port to a target input port
 | `targetNodeId` | string | yes | ID of the target node. |
 | `targetPortIndex` | number | yes | Index into the target node's `inputs` array. |
 | `waypoints` | array | no | Route control points. UI-only, no simulation semantics. |
+| `label` | string | no | Text shown on the wire, e.g. a signal name. UI-only, no simulation semantics. |
 
 **Fan-out:** A single output port can connect to multiple input ports (multiple connections share the same `sourceNodeId`/`sourcePortIndex`).
 
diff --git a/src/lib/components/canvas/flowConverters.ts b/src/lib/components/canvas/flowConverters.ts
index 6407b209..712ebc09 100644
--- a/src/lib/components/canvas/flowConverters.ts
+++ b/src/lib/components/canvas/flowConverters.ts
@@ -56,7 +56,7 @@ export function toFlowEdge(conn: Connection): Edge {
 		target: conn.targetNodeId,
 		targetHandle: HANDLE_ID.input(conn.targetNodeId, conn.targetPortIndex),
 		type: 'orthogonal',
-		data: { waypoints: conn.waypoints },
+		data: { waypoints: conn.waypoints, label: conn.label },
 		selectable: true,
 		deletable: true,
 		animated: false
diff --git a/src/lib/components/contextMenuBuilders.ts b/src/lib/components/contextMenuBuilders.ts
index 645194be..e1be1ef6 100644
--- a/src/lib/components/contextMenuBuilders.ts
+++ b/src/lib/components/contextMenuBuilders.ts
@@ -9,6 +9,7 @@ import type { ContextMenuTarget } from '$lib/stores/contextMenu';
 import { graphStore, ANNOTATION_FONT_SIZE } from '$lib/stores/graph';
 import { historyStore } from '$lib/stores/history';
 import { routingStore } from '$lib/stores/routing';
+import { editEdgeLabel } from '$lib/stores/edgeLabelEdit.svelte';
 import { eventStore } from '$lib/stores/events';
 import { clipboardStore } from '$lib/stores/clipboard';
 import { codePreviewStore } from '$lib/stores/codePreview';
@@ -400,6 +401,11 @@ function buildEventMenu(eventId: string): MenuItemType[] {
  */
 function buildEdgeMenu(edgeId: string): MenuItemType[] {
 	return [
+		{
+			label: 'Edit Label',
+			icon: 'tag',
+			action: () => editEdgeLabel(edgeId)
+		},
 		{
 			label: 'Reset Route',
 			icon: 'rotate',
diff --git a/src/lib/components/edges/OrthogonalEdge.svelte b/src/lib/components/edges/OrthogonalEdge.svelte
index 5aba0f89..c5c5c485 100644
--- a/src/lib/components/edges/OrthogonalEdge.svelte
+++ b/src/lib/components/edges/OrthogonalEdge.svelte
@@ -26,12 +26,15 @@
 </script>
 
 <script lang="ts">
-	import { BaseEdge, getSmoothStepPath, type EdgeProps, Position } from '@xyflow/svelte';
+	import { BaseEdge, EdgeLabel, getSmoothStepPath, type EdgeProps, Position } from '@xyflow/svelte';
 	import { routingStore } from '$lib/stores/routing';
+	import { graphStore } from '$lib/stores/graph';
 	import { edgeHighlights } from '$lib/stores/edgeHighlight';
+	import { edgeLabelEdit, editEdgeLabel } from '$lib/stores/edgeLabelEdit.svelte';
 	import { historyStore } from '$lib/stores/history';
 	import { screenToFlow } from '$lib/utils/viewUtils';
 	import { GRID_SIZE, EDGE_SOURCE_OFFSET, EDGE_TARGET_OFFSET, EDGE_CORNER_RADIUS } from '$lib/routing/constants';
+	import { EDGE_LABEL } from '$lib/constants/dimensions';
 	import type { Direction, RouteResult } from '$lib/routing';
 	import type { Waypoint } from '$lib/types/nodes';
 
@@ -295,6 +298,78 @@
 		return midpoints;
 	});
 
+	// Connection label, shown on the middle of the longest route segment
+	const label = $derived((data as { label?: string } | undefined)?.label ?? '');
+	const isEditingLabel = $derived(edgeLabelEdit.connectionId === id);
+
+	// Editor width follows the typed text
+	let draftLength = $state(0);
+
+	const labelAnchor = $derived.by(() => {
+		if (!label && !isEditingLabel) return null;
+		const points = displayedRoute
+			? [adjustedSource, ...displayedRoute.path, adjustedTarget]
+			: [adjustedSource, adjustedTarget];
+		let anchor = points[0];
+		let longest = -1;
+		for (let i = 0; i < points.length - 1; i++) {
+			const length = Math.abs(points[i + 1].x - points[i].x) + Math.abs(points[i + 1].y - points[i].y);
+			if (length > longest) {
+				longest = length;
+				anchor = { x: (points[i].x + points[i + 1].x) / 2, y: (points[i].y + points[i + 1].y) / 2 };
+			}
+		}
+		return anchor;
+	});
+
+	function handleEdgeDoubleClick(event: MouseEvent) {
+		event.stopPropagation();
+		editEdgeLabel(id);
+	}
+
+	function commitLabel(text: string) {
+		if (edgeLabelEdit.connectionId !== id) return;
+		editEdgeLabel(null);
+		if (text.trim() === label) return;
+		historyStore.mutate(() => graphStore.updateConnectionLabel(id, text));
+	}
+
+	/**
+	 * Label editor input. Enter commits, Escape cancels, a pointer press outside
+	 * the input commits. Blur alone never commits, because removing the editor
+	 * also blurs the input. Keys are stopped at the input so edge keyboard
+	 * handling and app shortcuts never see them. Focus waits until the input
+	 * sits in the label layer.
+	 */
+	function labelEditor(input: HTMLInputElement) {
+		const onKeydown = (event: KeyboardEvent) => {
+			event.stopPropagation();
+			if (event.key === 'Enter') commitLabel(input.value);
+			else if (event.key === 'Escape') editEdgeLabel(null);
+		};
+		const onPointerDown = (event: PointerEvent) => {
+			if (event.target !== input) commitLabel(input.value);
+		};
+		const onInput = () => {
+			draftLength = input.value.length;
+		};
+		draftLength = input.value.length;
+		input.addEventListener('keydown', onKeydown);
+		input.addEventListener('input', onInput);
+		document.addEventListener('pointerdown', onPointerDown, true);
+		requestAnimationFrame(() => {
+			input.focus();
+			input.select();
+		});
+		return {
+			destroy: () => {
+				input.removeEventListener('keydown', onKeydown);
+				input.removeEventListener('input', onInput);
+				document.removeEventListener('pointerdown', onPointerDown, true);
+			}
+		};
+	}
+
 	// Segment drag creates a waypoint, then drags it
 	function handleSegmentPointerDown(event: PointerEvent, segmentIndex: number) {
 		event.stopPropagation();
@@ -341,9 +416,11 @@
 	}
 </script>
 
+<!-- svelte-ignore a11y_no_static_element_interactions -->
 <g
 	class:highlighted={highlightColor !== undefined}
 	style={highlightColor !== undefined ? `--highlight-color: ${highlightColor}` : undefined}
+	ondblclick={handleEdgeDoubleClick}
 >
 	<BaseEdge {id} {path} {style} />
 
@@ -386,8 +463,30 @@
 			class:highlighted={highlightColor !== undefined}
 		/>
 	</g>
+
+	{#if label && !isEditingLabel && labelAnchor}
+		<text
+			x={labelAnchor.x}
+			y={labelAnchor.y}
+			class="edge-label"
+			class:selected
+			class:highlighted={highlightColor !== undefined}>{label}</text
+		>
+	{/if}
 </g>
 
+{#if isEditingLabel && labelAnchor}
+	<EdgeLabel x={labelAnchor.x} y={labelAnchor.y} transparent>
+		<input
+			class="edge-label-input"
+			style="--label-height: {EDGE_LABEL.height}px; --label-padding-x: {EDGE_LABEL.paddingX}px; --label-chars: {Math.max(draftLength, EDGE_LABEL.minChars)};"
+			value={label}
+			placeholder="Label"
+			use:labelEditor
+		/>
+	</EdgeLabel>
+{/if}
+
 <style>
 	.edge-arrow {
 		fill: var(--edge);
@@ -415,6 +514,51 @@
 		stroke: var(--highlight-color, var(--accent)) !important;
 	}
 
+	/* Connection label with a halo in the canvas color, readable on top of wires.
+	 * Pointer events pass through to the wire, so hovering the label hovers the edge. */
+	.edge-label {
+		font-family: var(--font-ui);
+		font-size: var(--font-xs);
+		fill: var(--text-muted);
+		stroke: var(--surface);
+		stroke-width: 3px;
+		stroke-linejoin: round;
+		paint-order: stroke;
+		text-anchor: middle;
+		dominant-baseline: central;
+		pointer-events: none;
+		transition: fill 0.15s ease;
+	}
+
+	:global(.svelte-flow__edge:hover) .edge-label,
+	.edge-label.selected {
+		fill: var(--accent);
+	}
+
+	.edge-label.highlighted {
+		fill: var(--highlight-color, var(--accent));
+	}
+
+	/* Inline label editor: same capsule, active like a dragged waypoint */
+	.edge-label-input {
+		box-sizing: border-box;
+		height: var(--label-height);
+		width: calc(var(--label-chars) * 1ch + 2 * var(--label-padding-x));
+		padding: 0 var(--label-padding-x);
+		border: 1.5px solid var(--accent);
+		border-radius: calc(var(--label-height) / 2);
+		background: var(--surface);
+		color: var(--text);
+		font-family: var(--font-ui);
+		font-size: var(--font-xs);
+		text-align: center;
+		outline: none;
+	}
+
+	.edge-label-input::placeholder {
+		color: var(--text-muted);
+	}
+
 	/* Waypoint group - visibility controlled by inline styles */
 	.waypoint-group {
 		transition: opacity 0.1s ease;
diff --git a/src/lib/constants/dimensions.ts b/src/lib/constants/dimensions.ts
index e9cc39f5..8f5f3958 100644
--- a/src/lib/constants/dimensions.ts
+++ b/src/lib/constants/dimensions.ts
@@ -36,6 +36,16 @@ export const HANDLE = {
 	hollowInset: 1.5
 } as const;
 
+/** Connection label capsule, shared by the drawn label and its inline editor */
+export const EDGE_LABEL = {
+	/** Capsule height in pixels */
+	height: 14,
+	/** Space between text and capsule ends in pixels */
+	paddingX: 6,
+	/** Minimum editor width in characters */
+	minChars: 5
+} as const;
+
 /** Event node dimensions (grid-aligned) */
 export const EVENT = {
 	/** Total bounding box size: 8 grid units = 80px */
diff --git a/src/lib/stores/clipboard.ts b/src/lib/stores/clipboard.ts
index 6ae94bf5..f5243666 100644
--- a/src/lib/stores/clipboard.ts
+++ b/src/lib/stores/clipboard.ts
@@ -340,7 +340,8 @@ async function paste(targetPosition: Position): Promise<{ nodeIds: string[]; eve
 					sourceNodeId: newSourceId,
 					sourcePortIndex: conn.sourcePortIndex,
 					targetNodeId: newTargetId,
-					targetPortIndex: conn.targetPortIndex
+					targetPortIndex: conn.targetPortIndex,
+					...(conn.label ? { label: conn.label } : {})
 				});
 			}
 		}
diff --git a/src/lib/stores/edgeLabelEdit.svelte.ts b/src/lib/stores/edgeLabelEdit.svelte.ts
new file mode 100644
index 00000000..2e74877e
--- /dev/null
+++ b/src/lib/stores/edgeLabelEdit.svelte.ts
@@ -0,0 +1,10 @@
+/**
+ * Edge label editing - which connection currently shows the inline label editor
+ */
+
+export const edgeLabelEdit = $state<{ connectionId: string | null }>({ connectionId: null });
+
+/** Open the label editor for a connection, or close it with null */
+export function editEdgeLabel(connectionId: string | null): void {
+	edgeLabelEdit.connectionId = connectionId;
+}
diff --git a/src/lib/stores/graph/connections.ts b/src/lib/stores/graph/connections.ts
index e28e1d3e..857decb4 100644
--- a/src/lib/stores/graph/connections.ts
+++ b/src/lib/stores/graph/connections.ts
@@ -107,3 +107,19 @@ export function updateConnectionWaypoints(id: string, waypoints: Waypoint[]): vo
 		connections.map((c) => (c.id === id ? { ...c, waypoints } : c))
 	);
 }
+
+/**
+ * Set the label of a connection; empty text removes it
+ */
+export function updateConnectionLabel(id: string, label: string): void {
+	const text = label.trim();
+	updateCurrentConnections((connections) =>
+		connections.map((c) => {
+			if (c.id !== id) return c;
+			const next = { ...c };
+			if (text) next.label = text;
+			else delete next.label;
+			return next;
+		})
+	);
+}
diff --git a/src/lib/stores/graph/index.ts b/src/lib/stores/graph/index.ts
index 8d8e6722..e5a91fab 100644
--- a/src/lib/stores/graph/index.ts
+++ b/src/lib/stores/graph/index.ts
@@ -78,6 +78,7 @@ export const graphStore = {
 	removeConnection: connections.removeConnection,
 	getAllConnections: connections.getAllConnections,
 	updateConnectionWaypoints: connections.updateConnectionWaypoints,
+	updateConnectionLabel: connections.updateConnectionLabel,
 
 	// ==================== PORT OPERATIONS ====================
 	addInputPort: ports.addInputPort,
diff --git a/src/lib/stores/graph/nodes.ts b/src/lib/stores/graph/nodes.ts
index bf4a22aa..14be59ab 100644
--- a/src/lib/stores/graph/nodes.ts
+++ b/src/lib/stores/graph/nodes.ts
@@ -363,7 +363,8 @@ export function duplicateSelected(): string[] {
 				sourceNodeId: newSourceId,
 				sourcePortIndex: conn.sourcePortIndex,
 				targetNodeId: newTargetId,
-				targetPortIndex: conn.targetPortIndex
+				targetPortIndex: conn.targetPortIndex,
+				...(conn.label ? { label: conn.label } : {})
 			});
 		}
 	}
diff --git a/src/lib/types/nodes.ts b/src/lib/types/nodes.ts
index 5a1b8594..611cebc5 100644
--- a/src/lib/types/nodes.ts
+++ b/src/lib/types/nodes.ts
@@ -137,6 +137,7 @@ export interface Connection {
 	targetNodeId: string;
 	targetPortIndex: number;
 	waypoints?: Waypoint[]; // Optional - empty/undefined means auto-route entire path
+	label?: string; // Optional text shown on the wire (UI-only)
 }
 
 /** Canvas annotation (markdown/LaTeX text) */