fix(library): separate required interface sockets

Author: FelixTJDietrich

.changeset/orthogonal-edge-routing.md

@@ -2,4 +2,4 @@
 "@tumaet/apollon": minor
 ---
 
-Edges now route themselves far more cleanly. They avoid unnecessary corners and crossings, run straight when two shapes line up, leave a node from a suitable side, and divide each available node side into balanced grid-aligned stretches — one edge centres itself, two edges make three even gaps, and larger groups spread the same way — instead of piling into a corner, stepping when they could be straight, or looping around another edge. Required-interface sockets stay concentric with their interface circles, including interfaces imported at an older size. Pin multiple endpoints to the same seat to form a stable shared junction; its common trunk is preserved intentionally, and opposing pinned branches use a balanced grid-aligned turn lane. Dragging an endpoint preserves its attachment while the route remains eligible for layout; dragging a bend preserves the route you authored. In both cases, neighbouring edges adapt without jumping on release, and node dragging remains substantially more responsive in edge-dense diagrams. Automatic results are deterministic, so every collaborator and a reloaded page see the same picture. Existing v3 diagrams and older v4 files with pre-routing edge data continue to open and are upgraded automatically.
+Edges now route themselves far more cleanly. They avoid unnecessary corners and crossings, run straight when two shapes line up, leave a node from a suitable side, and divide each available node side into balanced grid-aligned stretches — one edge centres itself, two edges make three even gaps, and larger groups spread the same way — instead of piling into a corner, stepping when they could be straight, or looping around another edge. Required-interface sockets stay concentric with their interface circles, including interfaces imported at an older size; relationship lines stop with visible breathing room before the socket, while its arc adapts to the sides the finished routes actually use. Pin multiple endpoints to the same seat to form a stable shared junction; its common trunk is preserved intentionally, and opposing pinned branches use a balanced grid-aligned turn lane. Dragging an endpoint preserves its attachment while the route remains eligible for layout; dragging a bend preserves the route you authored. In both cases, neighbouring edges adapt without jumping on release, and node dragging remains substantially more responsive in edge-dense diagrams. Automatic results are deterministic, so every collaborator and a reloaded page see the same picture. Existing v3 diagrams and older v4 files with pre-routing edge data continue to open and are upgraded automatically.

library/lib/constants.ts

@@ -291,7 +291,11 @@ export const MARKER_CONFIGS = Object.freeze({
     size: INTERFACE_SOCKET_SIZE,
     widthFactor: 1,
     heightFactor: 1,
-    arcSpanDegrees: 180,
+    // A slightly embracing socket reads more clearly around the ball than a
+    // mathematically exact half-circle, especially when approached from a
+    // cardinal side. Keep a generous opening so adjacent sockets remain
+    // visually distinct.
+    arcSpanDegrees: 210,
   },
   "required-interface-quarter": {
     type: "semicircle",

library/lib/edges/edgeTypes/ComponentDiagramEdge.tsx

@@ -7,7 +7,7 @@ import { useToolbar } from "@/hooks"
 import { FeedbackDropzone } from "@/components/wrapper/FeedbackDropzone"
 import { AssessmentSelectableWrapper } from "@/components"
 import { getCustomColorsFromDataForEdge } from "@/utils/layoutUtils"
-import { resolveRequiredInterfaceEdgeType } from "@/utils"
+import { useRequiredInterfaceEdgeType } from "@/hooks/useRequiredInterfaceEdgeType"
 
 const COMPONENT_REQUIRED_INTERFACE_TYPES = [
   "ComponentRequiredInterface",
@@ -44,23 +44,17 @@ export const ComponentDiagramEdge = ({
   const allowMidpointDragging =
     "allowMidpointDragging" in config ? config.allowMidpointDragging : true
 
-  const { edges, assessments } = useDiagramStore(
-    useShallow((state) => ({
-      edges: state.edges,
-      assessments: state.assessments,
-    }))
-  )
+  const assessments = useDiagramStore(useShallow((state) => state.assessments))
 
   const setPopOverElementId = usePopoverStore(
     useShallow((state) => state.setPopOverElementId)
   )
 
-  const dynamicEdgeType = resolveRequiredInterfaceEdgeType({
+  const dynamicEdgeType = useRequiredInterfaceEdgeType({
     type,
     id,
     target,
     targetHandleId,
-    edges,
     requiredTypes: COMPONENT_REQUIRED_INTERFACE_TYPES,
     defaultType: "ComponentRequiredInterface",
     reducedType: "ComponentRequiredQuarterInterface",

library/lib/edges/edgeTypes/DeploymentDiagramEdge.tsx

@@ -8,7 +8,7 @@ import { useToolbar } from "@/hooks"
 import { FeedbackDropzone } from "@/components/wrapper/FeedbackDropzone"
 import { AssessmentSelectableWrapper } from "@/components"
 import { getCustomColorsFromDataForEdge } from "@/utils/layoutUtils"
-import { resolveRequiredInterfaceEdgeType } from "@/utils"
+import { useRequiredInterfaceEdgeType } from "@/hooks/useRequiredInterfaceEdgeType"
 
 const DEPLOYMENT_REQUIRED_INTERFACE_TYPES = [
   "DeploymentRequiredInterface",
@@ -47,23 +47,17 @@ export const DeploymentDiagramEdge = ({
   const showRelationshipLabels =
     "showRelationshipLabels" in config ? config.showRelationshipLabels : false
 
-  const { edges, assessments } = useDiagramStore(
-    useShallow((state) => ({
-      edges: state.edges,
-      assessments: state.assessments,
-    }))
-  )
+  const assessments = useDiagramStore(useShallow((state) => state.assessments))
 
   const setPopOverElementId = usePopoverStore(
     useShallow((state) => state.setPopOverElementId)
   )
 
-  const dynamicEdgeType = resolveRequiredInterfaceEdgeType({
+  const dynamicEdgeType = useRequiredInterfaceEdgeType({
     type,
     id,
     target,
     targetHandleId,
-    edges,
     requiredTypes: DEPLOYMENT_REQUIRED_INTERFACE_TYPES,
     defaultType: "DeploymentRequiredInterface",
     reducedType: "DeploymentRequiredQuarterInterface",

library/lib/hooks/index.ts

@@ -13,5 +13,6 @@ export * from "./useKeyboardShortcuts"
 export * from "./useDragOver"
 export * from "./useStepPathEdge"
 export * from "./useStraightPathEdge"
+export * from "./useRequiredInterfaceEdgeType"
 export * from "./useAssessmentSelection"
 export * from "./usePaneClicked"

library/lib/hooks/useRequiredInterfaceEdgeType.ts

@@ -0,0 +1,82 @@
+import { useMemo } from "react"
+import { useShallow } from "zustand/shallow"
+import { useDiagramStore, useEdgeGeometryStore } from "@/store/context"
+import { getEndpointSideFromSegment } from "@/utils/edgeUtils"
+import { resolveRequiredInterfaceEdgeType } from "@/utils/requiredInterfaceUtils"
+
+type RequiredInterfaceEdgeTypeOptions = {
+  type: string
+  id: string
+  target: string
+  targetHandleId?: string | null
+  requiredTypes: readonly string[]
+  defaultType: string
+  reducedType: string
+}
+
+/**
+ * Choose a socket span from the actual holistic route sides. Stored handle ids
+ * remain the pre-solve fallback, but once auto-layout moves a terminal segment
+ * the marker follows the visible geometry. Only routes sharing this interface
+ * are selected, so unrelated geometry updates do not re-render the edge.
+ */
+export function useRequiredInterfaceEdgeType({
+  type,
+  id,
+  target,
+  targetHandleId,
+  requiredTypes,
+  defaultType,
+  reducedType,
+}: RequiredInterfaceEdgeTypeOptions): string {
+  const edges = useDiagramStore(useShallow((state) => state.edges))
+  const requiredTargetEdges = useMemo(
+    () =>
+      edges.filter(
+        (edge) =>
+          edge.target === target &&
+          edge.type !== undefined &&
+          requiredTypes.includes(edge.type)
+      ),
+    [edges, requiredTypes, target]
+  )
+  const requiredTargetIds = useMemo(
+    () => requiredTargetEdges.map((edge) => edge.id),
+    [requiredTargetEdges]
+  )
+  const targetPositions = useEdgeGeometryStore(
+    useShallow((state) =>
+      requiredTargetIds.map((edgeId) => {
+        const route = state.previewById[edgeId] ?? state.geometryById[edgeId]
+        return route && route.length >= 2
+          ? getEndpointSideFromSegment(
+              route[route.length - 1],
+              route[route.length - 2]
+            )
+          : undefined
+      })
+    )
+  )
+  const targetPositionByEdgeId = useMemo(
+    () =>
+      new Map(
+        requiredTargetIds.flatMap((edgeId, index) => {
+          const position = targetPositions[index]
+          return position ? [[edgeId, position] as const] : []
+        })
+      ),
+    [requiredTargetIds, targetPositions]
+  )
+
+  return resolveRequiredInterfaceEdgeType({
+    type,
+    id,
+    target,
+    targetHandleId,
+    edges,
+    requiredTypes,
+    defaultType,
+    reducedType,
+    targetPositionByEdgeId,
+  })
+}

library/lib/hooks/useStepPathEdge.ts

@@ -35,6 +35,8 @@ import {
   resolveOrthogonalEdgeReleasePoints,
   isInvalidOrthogonalEdgeRelease,
   getSideHandleIdForPosition,
+  getEndpointSideFromSegment,
+  getTargetConnectionPointPadding,
   isFreeformEdgeAnchor,
   roundAnchorPointOutward,
   type FreeformEdgeAnchor,
@@ -136,18 +138,6 @@ const arePointsEqual = (a: IPoint[], b: IPoint[]): boolean =>
   a.length === b.length &&
   a.every((point, index) => point.x === b[index].x && point.y === b[index].y)
 
-/** The node side an endpoint sits on, read off the route: `from` is the endpoint,
- * `toward` the next point along. The first step leaves the source along its side,
- * so the direction from the source to its neighbour IS that side; at the target,
- * pass the points in reverse (endpoint, then inward neighbour). */
-const sideFromSegment = (from: IPoint, toward: IPoint): Position => {
-  const dx = toward.x - from.x
-  const dy = toward.y - from.y
-  if (Math.abs(dx) >= Math.abs(dy))
-    return dx >= 0 ? Position.Right : Position.Left
-  return dy >= 0 ? Position.Bottom : Position.Top
-}
-
 export const useStepPathEdge = ({
   id,
   type,
@@ -406,7 +396,10 @@ export const useStepPathEdge = ({
   const sourceConnectionPointPadding = resolvedSourceAnchor
     ? 0
     : EDGES.SOURCE_CONNECTION_POINT_PADDING
-  const targetConnectionPointPadding = resolvedTargetAnchor ? 0 : padding
+  const targetConnectionPointPadding = getTargetConnectionPointPadding(
+    padding,
+    resolvedTargetAnchor !== null
+  )
 
   // Round coordinates to whole pixels for pixel-perfect rendering
   // React Flow may return fractional values when node dimensions are odd
@@ -445,10 +438,10 @@ export const useStepPathEdge = ({
   const routeEndpoints =
     centralRoute && centralRoute.length >= 2 ? centralRoute : null
   const sourcePosition = routeEndpoints
-    ? sideFromSegment(routeEndpoints[0], routeEndpoints[1])
+    ? getEndpointSideFromSegment(routeEndpoints[0], routeEndpoints[1])
     : baseSourcePosition
   const targetPosition = routeEndpoints
-    ? sideFromSegment(
+    ? getEndpointSideFromSegment(
         routeEndpoints[routeEndpoints.length - 1],
         routeEndpoints[routeEndpoints.length - 2]
       )

library/lib/hooks/useStraightPathEdge.ts

@@ -14,6 +14,7 @@ import {
   getEdgeMarkerStyles,
   adjustSourceCoordinates,
   adjustTargetCoordinates,
+  getTargetConnectionPointPadding,
   getSideHandleIdForPosition,
   isFreeformEdgeAnchor,
   roundAnchorPointOutward,
@@ -262,7 +263,10 @@ export const useStraightPathEdge = ({
   const sourceConnectionPointPadding = resolvedSourceAnchor
     ? 0
     : EDGES.SOURCE_CONNECTION_POINT_PADDING
-  const targetConnectionPointPadding = resolvedTargetAnchor ? 0 : padding
+  const targetConnectionPointPadding = getTargetConnectionPointPadding(
+    padding,
+    resolvedTargetAnchor !== null
+  )
 
   // Round coordinates to whole pixels for pixel-perfect rendering
   // React Flow may return fractional values when node dimensions are odd

library/lib/utils/edgeUtils.ts

@@ -52,6 +52,38 @@ export const adjustSourceCoordinates = (
   return { sourceX, sourceY }
 }
 
+/**
+ * Convert marker padding from React Flow handle coordinates to a
+ * shape-projected anchor.
+ *
+ * Unpinned endpoints start at an RF handle whose center is
+ * `-EDGES.MARKER_PADDING` pixels outside the node. A projected/pinned anchor
+ * already lies on the exact shape boundary, so only the marker-specific
+ * remainder belongs there. Keeping this conversion shared prevents the
+ * centralized router and the two rendering hooks from disagreeing.
+ */
+export const getTargetConnectionPointPadding = (
+  markerPadding: number,
+  hasResolvedAnchor: boolean
+): number =>
+  hasResolvedAnchor ? markerPadding - EDGES.MARKER_PADDING : markerPadding
+
+/**
+ * Resolve the node side occupied by an endpoint from its terminal segment.
+ * `from` is the endpoint and `toward` is its neighboring route point, so this
+ * works for a source as-is and for a target when the route is read backwards.
+ */
+export const getEndpointSideFromSegment = (
+  from: IPoint,
+  toward: IPoint
+): Position => {
+  const dx = toward.x - from.x
+  const dy = toward.y - from.y
+  if (Math.abs(dx) >= Math.abs(dy))
+    return dx >= 0 ? Position.Right : Position.Left
+  return dy >= 0 ? Position.Bottom : Position.Top
+}
+
 /**
  * Round a shape-projected connection point without moving it back inside its
  * node. Fractional text measurements make this distinction observable at the
@@ -280,26 +312,36 @@ export function getEdgeMarkerStyles(edgeType: string): EdgeMarkerStyles {
     case "ComponentRequiredInterface":
     case "DeploymentRequiredInterface":
       return {
-        // markerPadding = MARKER_PADDING + gap
+        // markerPadding = MARKER_PADDING + ball/socket gap + line/socket gap
         // MARKER_PADDING (-3) compensates for React Flow handle offset
-        // gap is the spacing between socket arc and ball circle
-        markerPadding: EDGES.MARKER_PADDING + INTERFACE.SOCKET_GAP,
+        // SOCKET_GAP keeps the arc off the ball, while EDGE_SOCKET_GAP keeps
+        // the relationship line from visually merging into the arc.
+        markerPadding:
+          EDGES.MARKER_PADDING +
+          INTERFACE.SOCKET_GAP +
+          INTERFACE.EDGE_SOCKET_GAP,
         markerEnd: "url(#required-interface)",
         strokeDashArray: "0",
         offset: 0,
       }
     case "ComponentRequiredQuarterInterface":
     case "DeploymentRequiredQuarterInterface":
       return {
-        markerPadding: EDGES.MARKER_PADDING + INTERFACE.SOCKET_GAP,
+        markerPadding:
+          EDGES.MARKER_PADDING +
+          INTERFACE.SOCKET_GAP +
+          INTERFACE.EDGE_SOCKET_GAP,
         markerEnd: "url(#required-interface-quarter)",
         strokeDashArray: "0",
         offset: 0,
       }
     case "ComponentRequiredThreeQuarterInterface":
     case "DeploymentRequiredThreeQuarterInterface":
       return {
-        markerPadding: EDGES.MARKER_PADDING + INTERFACE.SOCKET_GAP,
+        markerPadding:
+          EDGES.MARKER_PADDING +
+          INTERFACE.SOCKET_GAP +
+          INTERFACE.EDGE_SOCKET_GAP,
         markerEnd: "url(#required-interface-threequarter)",
         strokeDashArray: "0",
         offset: 0,

library/lib/utils/geometry/edgeGeometrySolver.ts

@@ -12,6 +12,7 @@ import {
   adjustSourceCoordinates,
   adjustTargetCoordinates,
   getEdgeMarkerStyles,
+  getTargetConnectionPointPadding,
   preserveOrthogonalEdgePoints,
   isFreeformEdgeAnchor,
   roundAnchorPointOutward,
@@ -191,7 +192,10 @@ function resolveEdgeEndpoints(
   const sourceConnectionPointPadding = resolvedSourceAnchor
     ? 0
     : EDGES.SOURCE_CONNECTION_POINT_PADDING
-  const targetConnectionPointPadding = resolvedTargetAnchor ? 0 : padding
+  const targetConnectionPointPadding = getTargetConnectionPointPadding(
+    padding,
+    resolvedTargetAnchor !== null
+  )
 
   const roundedSource = resolvedSourceAnchor
     ? roundAnchorPointOutward(resolvedSourceAnchor.point, sourcePosition)