fix(library): refine required interface seams

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; 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.
+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 join the socket cleanly, while its arc adapts to the sides the finished routes actually use and remains visually distinct from neighbouring sockets and provided edges. 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,27 +291,28 @@ export const MARKER_CONFIGS = Object.freeze({
     size: INTERFACE_SOCKET_SIZE,
     widthFactor: 1,
     heightFactor: 1,
-    // 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,
+    // Two opposing sockets leave an 8° seam at both joins instead of merging
+    // into a visually indistinguishable 360° ring. At the canonical 18px
+    // socket radius, 8° is the smallest grid-friendly seam that also clears a
+    // provided-interface line passing through it at the current stroke width.
+    arcSpanDegrees: 172,
   },
   "required-interface-quarter": {
     type: "semicircle",
     filled: false,
     size: INTERFACE_SOCKET_SIZE,
     widthFactor: 1,
     heightFactor: 1,
-    arcSpanDegrees: 90,
+    // Adjacent cardinal sockets retain the same 5° seam.
+    arcSpanDegrees: 85,
   },
   "required-interface-threequarter": {
     type: "semicircle",
     filled: false,
     size: INTERFACE_SOCKET_SIZE,
     widthFactor: 1,
     heightFactor: 1,
-    arcSpanDegrees: 270,
+    arcSpanDegrees: 265,
   },
   // BPMN markers - compact style
   "bpmn-white-triangle": {

library/lib/utils/edgeUtils.ts

@@ -312,36 +312,27 @@ export function getEdgeMarkerStyles(edgeType: string): EdgeMarkerStyles {
     case "ComponentRequiredInterface":
     case "DeploymentRequiredInterface":
       return {
-        // markerPadding = MARKER_PADDING + ball/socket gap + line/socket gap
+        // markerPadding = MARKER_PADDING + ball/socket gap
         // MARKER_PADDING (-3) compensates for React Flow handle offset
-        // 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,
+        // SOCKET_GAP moves the line endpoint onto the socket's outermost point:
+        // the relationship joins its arc, while the arc stays off the ball.
+        markerPadding: EDGES.MARKER_PADDING + INTERFACE.SOCKET_GAP,
         markerEnd: "url(#required-interface)",
         strokeDashArray: "0",
         offset: 0,
       }
     case "ComponentRequiredQuarterInterface":
     case "DeploymentRequiredQuarterInterface":
       return {
-        markerPadding:
-          EDGES.MARKER_PADDING +
-          INTERFACE.SOCKET_GAP +
-          INTERFACE.EDGE_SOCKET_GAP,
+        markerPadding: EDGES.MARKER_PADDING + INTERFACE.SOCKET_GAP,
         markerEnd: "url(#required-interface-quarter)",
         strokeDashArray: "0",
         offset: 0,
       }
     case "ComponentRequiredThreeQuarterInterface":
     case "DeploymentRequiredThreeQuarterInterface":
       return {
-        markerPadding:
-          EDGES.MARKER_PADDING +
-          INTERFACE.SOCKET_GAP +
-          INTERFACE.EDGE_SOCKET_GAP,
+        markerPadding: EDGES.MARKER_PADDING + INTERFACE.SOCKET_GAP,
         markerEnd: "url(#required-interface-threequarter)",
         strokeDashArray: "0",
         offset: 0,

library/lib/utils/geometry/routingConstants.ts

@@ -18,19 +18,15 @@ export const CANVAS = Object.freeze({
 const INTERFACE_SIZE = 30
 const INTERFACE_RADIUS = INTERFACE_SIZE / 2
 const INTERFACE_STROKE_WIDTH = 2
-const INTERFACE_SOCKET_GAP = 4
-// Keep the relationship line visibly separate from the required-interface
-// socket. React Flow places its handle center 3px outside the node; routing
-// padding accounts for that independently, so this is the actual canvas-space
-// air gap between the line endpoint and the socket stroke centerline.
-const INTERFACE_EDGE_SOCKET_GAP = 3
+// The socket is concentric with the provided-interface ball. With two 2px
+// strokes, a 3px centerline difference leaves a crisp 1px visible gap.
+const INTERFACE_SOCKET_GAP = 3
 
 export const INTERFACE = Object.freeze({
   SIZE: INTERFACE_SIZE,
   RADIUS: INTERFACE_RADIUS,
   STROKE_WIDTH: INTERFACE_STROKE_WIDTH,
   SOCKET_GAP: INTERFACE_SOCKET_GAP,
-  EDGE_SOCKET_GAP: INTERFACE_EDGE_SOCKET_GAP,
 } as const)
 
 export const EDGES = Object.freeze({

library/tests/unit/edgeGeometrySolver.test.ts

@@ -96,7 +96,7 @@ describe("computeAllEdgeGeometry", () => {
     "ComponentRequiredInterface",
     "ComponentRequiredQuarterInterface",
     "ComponentRequiredThreeQuarterInterface",
-  ])("keeps %s lines separated from a pinned interface socket", (type) => {
+  ])("joins %s lines to a pinned interface socket", (type) => {
     const source = makeNode("source", 0, 0)
     const target = makeNode(
       "interface",
@@ -135,10 +135,7 @@ describe("computeAllEdgeGeometry", () => {
     const route = routeById.required
     const targetPoint = route[route.length - 1]
     expect(targetPoint).toEqual({
-      x:
-        target.node.position.x -
-        INTERFACE.SOCKET_GAP -
-        INTERFACE.EDGE_SOCKET_GAP,
+      x: target.node.position.x - INTERFACE.SOCKET_GAP,
       y: target.node.position.y + INTERFACE.RADIUS,
     })
   })

library/tests/unit/edgeUtils.test.ts

@@ -274,7 +274,7 @@ describe("getEdgeMarkerStyles", () => {
     {
       type: "ComponentRequiredInterface",
       end: "url(#required-interface)",
-      pad: MP + INTERFACE.SOCKET_GAP + INTERFACE.EDGE_SOCKET_GAP,
+      pad: MP + INTERFACE.SOCKET_GAP,
     },
     {
       type: "ComponentRequiredQuarterInterface",
@@ -312,11 +312,10 @@ describe("getTargetConnectionPointPadding", () => {
     expect(getTargetConnectionPointPadding(EDGES.MARKER_PADDING, true)).toBe(0)
   })
 
-  it("preserves the full ball-to-socket and line-to-socket gaps on an exact interface anchor", () => {
-    const requiredPadding =
-      EDGES.MARKER_PADDING + INTERFACE.SOCKET_GAP + INTERFACE.EDGE_SOCKET_GAP
+  it("preserves the ball-to-socket gap on an exact interface anchor", () => {
+    const requiredPadding = EDGES.MARKER_PADDING + INTERFACE.SOCKET_GAP
     expect(getTargetConnectionPointPadding(requiredPadding, true)).toBe(
-      INTERFACE.SOCKET_GAP + INTERFACE.EDGE_SOCKET_GAP
+      INTERFACE.SOCKET_GAP
     )
   })
 })

library/tests/unit/markerGeometry.test.ts

@@ -60,10 +60,16 @@ describe("class diagram marker geometry", () => {
 })
 
 describe("required interface marker geometry", () => {
-  it("wraps the standard socket beyond a half-circle without closing it", () => {
+  it("leaves a stroke-safe seam between opposing standard sockets", () => {
     const span = MARKER_CONFIGS["required-interface"].arcSpanDegrees
-    expect(span).toBeGreaterThan(180)
-    expect(span).toBeLessThan(270)
+    expect(span).toBe(172)
+    expect(180 - span).toBeGreaterThanOrEqual(5)
+  })
+
+  it("leaves a five-degree seam between adjacent reduced sockets", () => {
+    const span = MARKER_CONFIGS["required-interface-quarter"].arcSpanDegrees
+    expect(span).toBe(85)
+    expect(90 - span).toBe(5)
   })
 
   it.each([
@@ -98,8 +104,8 @@ describe("required interface marker geometry", () => {
   )
 
   it("scales its bounds with imported interface sizes", () => {
-    expect(getMarkerHalfHeight("required-interface", 10)).toBe(14)
-    expect(getMarkerHalfHeight("required-interface", 15)).toBe(19)
+    expect(getMarkerHalfHeight("required-interface", 10)).toBeCloseTo(13, 1)
+    expect(getMarkerHalfHeight("required-interface", 15)).toBeCloseTo(18, 1)
   })
 
   it.each([
@@ -108,7 +114,7 @@ describe("required interface marker geometry", () => {
     { position: Position.Right, direction: Math.PI },
     { position: Position.Bottom, direction: -Math.PI / 2 },
   ])(
-    "keeps a visible line-to-socket gap when entering from $position",
+    "joins the line to the socket when entering from $position",
     ({ position, direction }) => {
       const center = { x: 100, y: 100 }
       const towardTarget = {
@@ -146,7 +152,7 @@ describe("required interface marker geometry", () => {
 
       expect(
         Math.hypot(edgeEnd.x - socketPoint.x, edgeEnd.y - socketPoint.y)
-      ).toBe(INTERFACE.EDGE_SOCKET_GAP)
+      ).toBeCloseTo(0, 10)
     }
   )
 })

standalone/webapp/tests/visual/diagrams.visual.spec.ts

@@ -70,13 +70,13 @@ const REQUIRED_INTERFACE_TYPES = new Set([
   "ComponentRequiredThreeQuarterInterface",
   "DeploymentRequiredThreeQuarterInterface",
 ])
-const STANDARD_REQUIRED_INTERFACE_ARC_RADIANS = (210 * Math.PI) / 180
+const STANDARD_REQUIRED_INTERFACE_ARC_RADIANS = (172 * Math.PI) / 180
 
 /**
  * Whole-editor screenshots intentionally tolerate a small amount of
  * anti-aliasing noise. A required-interface socket occupies too few pixels for
  * that threshold to protect its topology, so assert its SVG geometry exactly:
- * the relationship must stop before the arc, and each socket variant must keep
+ * the relationship must join the arc, and each socket variant must keep
  * its intended angular span.
  */
 async function expectRequiredInterfaceGeometry(
@@ -125,7 +125,7 @@ async function expectRequiredInterfaceGeometry(
         }
       })
 
-    expect(geometry.minimumGap).toBeCloseTo(3, 1)
+    expect(geometry.minimumGap).toBeCloseTo(0, 1)
     const explicitExpectedArc = expectedArcByEdgeId?.[edge.id]
     if (explicitExpectedArc === undefined) {
       // Every interface in the canonical fixtures has one required edge. Its
@@ -142,6 +142,62 @@ async function expectRequiredInterfaceGeometry(
   }
 }
 
+async function expectProvidedInterfaceClearsRequiredSockets(
+  page: Page,
+  providedEdgeId: string,
+  requiredEdgeIds: readonly string[]
+) {
+  const clearance = await page.evaluate(
+    ({ providedEdgeId, requiredEdgeIds }) => {
+      const edgePath = (edgeId: string) =>
+        document.querySelector<SVGPathElement>(
+          `.react-flow__edge[data-id="${edgeId}"] path.react-flow__edge-path`
+        )
+      const provided = edgePath(providedEdgeId)
+      const sockets = requiredEdgeIds.map((edgeId) =>
+        document.querySelector<SVGPathElement>(
+          `.react-flow__edge[data-id="${edgeId}"] path[data-inline-marker="true"]`
+        )
+      )
+      if (!provided || sockets.some((socket) => socket === null))
+        throw new Error("provided/required interface paths are absent")
+
+      const sample = (path: SVGPathElement, count: number) =>
+        Array.from({ length: count + 1 }, (_, index) =>
+          path.getPointAtLength((path.getTotalLength() * index) / count)
+        )
+      const providedPoints = sample(provided, 360)
+      let minimumDistance = Number.POSITIVE_INFINITY
+      for (const socket of sockets as SVGPathElement[]) {
+        for (const edgePoint of providedPoints) {
+          for (const socketPoint of sample(socket, 720)) {
+            minimumDistance = Math.min(
+              minimumDistance,
+              Math.hypot(
+                edgePoint.x - socketPoint.x,
+                edgePoint.y - socketPoint.y
+              )
+            )
+          }
+        }
+      }
+
+      return {
+        minimumDistance,
+        providedHalfStroke:
+          Number.parseFloat(getComputedStyle(provided).strokeWidth) / 2,
+      }
+    },
+    { providedEdgeId, requiredEdgeIds }
+  )
+
+  // The required arcs use butt caps, so clearing the provided line's
+  // half-stroke is the exact non-intersection condition at their seam.
+  expect(clearance.minimumDistance).toBeGreaterThan(
+    clearance.providedHalfStroke
+  )
+}
+
 // All 13 diagram fixtures with human-readable name + kebab-case file slug.
 // `fitView: true` triggers the ReactFlow fit-view button so the full diagram
 // is visible — needed for diagrams that overflow the viewport at zoom 1.0.
@@ -306,6 +362,47 @@ const requiredInterfaceCombinationFixture = (
   assessments: {},
 })
 
+const requiredInterfaceWithProvidedFixture = (() => {
+  const fixture = requiredInterfaceCombinationFixture("socket-provided", {
+    x: 485,
+    y: 545,
+  })
+  return {
+    ...fixture,
+    nodes: [
+      ...fixture.nodes,
+      {
+        id: "socket-provided-subsystem",
+        width: 180,
+        height: 120,
+        type: "componentSubsystem",
+        position: { x: 725, y: 365 },
+        data: { name: "Subsystem", isComponentSubsystemHeaderShown: true },
+        measured: { width: 180, height: 120 },
+      },
+    ],
+    edges: [
+      ...fixture.edges,
+      {
+        id: "socket-provided-line",
+        source: "socket-provided-subsystem",
+        target: "socket-provided-interface",
+        type: "ComponentProvidedInterface",
+        sourceHandle: "left",
+        targetHandle: "right",
+        data: {
+          points: [
+            { x: 725, y: 435 },
+            { x: 610, y: 435 },
+          ],
+          sourceAnchor: { side: "left", ratio: 7 / 12 },
+          targetAnchor: { side: "right", ratio: 0.5 },
+        },
+      },
+    ],
+  }
+})()
+
 test.describe("Required interface socket combinations", () => {
   const cases = [
     {
@@ -322,7 +419,7 @@ test.describe("Required interface socket combinations", () => {
         x: 320,
         y: 390,
       }),
-      expectedArc: Math.PI / 2,
+      expectedArc: (85 * Math.PI) / 180,
     },
   ]
 
@@ -337,6 +434,28 @@ test.describe("Required interface socket combinations", () => {
       })
     })
   }
+
+  test("a provided edge passes cleanly through the seam between required sockets", async ({
+    page,
+  }) => {
+    const fixture = requiredInterfaceWithProvidedFixture
+    await injectFixtureIntoLocalStorage(page, fixture)
+    await page.goto(resolveLocalDiagramRoute(fixture))
+    await waitForCanvasReady(page)
+    const requiredEdgeIds = [
+      "socket-provided-side",
+      "socket-provided-top",
+    ] as const
+    await expectRequiredInterfaceGeometry(page, fixture, {
+      [requiredEdgeIds[0]]: STANDARD_REQUIRED_INTERFACE_ARC_RADIANS,
+      [requiredEdgeIds[1]]: STANDARD_REQUIRED_INTERFACE_ARC_RADIANS,
+    })
+    await expectProvidedInterfaceClearsRequiredSockets(
+      page,
+      "socket-provided-line",
+      requiredEdgeIds
+    )
+  })
 })
 
 // ---------------------------------------------------------------------------