feat: add line-jump on edge collision (#706)

Co-authored-by: Felix T.J. Dietrich <felix_dietrich@gmx.de>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

library/lib/apollon-editor.tsx

@@ -21,12 +21,17 @@ import {
   createAlignmentGuidesStore,
   AlignmentGuidesStore,
 } from "@/store/alignmentGuidesStore"
+import {
+  createEdgeGeometryStore,
+  EdgeGeometryStore,
+} from "@/store/edgeGeometryStore"
 import {
   DiagramStoreContext,
   MetadataStoreContext,
   PopoverStoreContext,
   AssessmentSelectionStoreContext,
   AlignmentGuidesStoreContext,
+  EdgeGeometryStoreContext,
 } from "./store/context"
 import { MessageType, SendBroadcastMessage, YjsSync } from "./sync/yjsSync"
 import * as Y from "yjs"
@@ -76,6 +81,7 @@ export class ApollonEditor {
   private readonly popoverStore: StoreApi<PopoverStore>
   private readonly assessmentSelectionStore: StoreApi<AssessmentSelectionStore>
   private readonly alignmentGuidesStore: StoreApi<AlignmentGuidesStore>
+  private readonly edgeGeometryStore: StoreApi<EdgeGeometryStore>
   private subscribers: Apollon.Subscribers = {}
   constructor(element: HTMLElement, options?: Apollon.ApollonOptions) {
     if (!(element instanceof HTMLElement)) {
@@ -91,6 +97,7 @@ export class ApollonEditor {
     this.popoverStore = createPopoverStore()
     this.assessmentSelectionStore = createAssessmentSelectionStore()
     this.alignmentGuidesStore = createAlignmentGuidesStore()
+    this.edgeGeometryStore = createEdgeGeometryStore()
     this.syncManager = new YjsSync(
       this.ydoc,
       this.diagramStore,
@@ -179,22 +186,26 @@ export class ApollonEditor {
               <AlignmentGuidesStoreContext.Provider
                 value={this.alignmentGuidesStore}
               >
-                <AppWithProvider
-                  onReactFlowInit={this.setReactFlowInstance.bind(this)}
-                  collaboration={collaboration}
-                  awareness={{
-                    setLocalAwarenessCursor:
-                      this.syncManager.setLocalAwarenessCursor,
-                    setLocalAwarenessSelectedElement:
-                      this.syncManager.setLocalAwarenessSelectedElement,
-                    subscribeToAwarenessChanges:
-                      this.syncManager.subscribeToAwarenessChanges,
-                    subscribeToCollaboratorChanges:
-                      this.syncManager.subscribeToCollaboratorChanges,
-                    getLocalAwarenessClientId:
-                      this.syncManager.getLocalAwarenessClientId,
-                  }}
-                />
+                <EdgeGeometryStoreContext.Provider
+                  value={this.edgeGeometryStore}
+                >
+                  <AppWithProvider
+                    onReactFlowInit={this.setReactFlowInstance.bind(this)}
+                    collaboration={collaboration}
+                    awareness={{
+                      setLocalAwarenessCursor:
+                        this.syncManager.setLocalAwarenessCursor,
+                      setLocalAwarenessSelectedElement:
+                        this.syncManager.setLocalAwarenessSelectedElement,
+                      subscribeToAwarenessChanges:
+                        this.syncManager.subscribeToAwarenessChanges,
+                      subscribeToCollaboratorChanges:
+                        this.syncManager.subscribeToCollaboratorChanges,
+                      getLocalAwarenessClientId:
+                        this.syncManager.getLocalAwarenessClientId,
+                    }}
+                  />
+                </EdgeGeometryStoreContext.Provider>
               </AlignmentGuidesStoreContext.Provider>
             </AssessmentSelectionStoreContext.Provider>
           </PopoverStoreContext.Provider>
@@ -320,6 +331,7 @@ export class ApollonEditor {
     const popoverStore = createPopoverStore()
     const assessmentSelectionStore = createAssessmentSelectionStore()
     const alignmentGuidesStore = createAlignmentGuidesStore()
+    const edgeGeometryStore = createEdgeGeometryStore()
     const diagramId = Math.random().toString(36).substring(2, 15)
 
     let setReactFlowInstance: (instance: ReactFlowInstance) => void = () => {}
@@ -347,11 +359,13 @@ export class ApollonEditor {
               <AlignmentGuidesStoreContext.Provider
                 value={alignmentGuidesStore}
               >
-                <AppWithProvider
-                  onReactFlowInit={setReactFlowInstance}
-                  collaboration={disabledCollaboration}
-                  awareness={noopCollaborationAwareness}
-                />
+                <EdgeGeometryStoreContext.Provider value={edgeGeometryStore}>
+                  <AppWithProvider
+                    onReactFlowInit={setReactFlowInstance}
+                    collaboration={disabledCollaboration}
+                    awareness={noopCollaborationAwareness}
+                  />
+                </EdgeGeometryStoreContext.Provider>
               </AlignmentGuidesStoreContext.Provider>
             </AssessmentSelectionStoreContext.Provider>
           </PopoverStoreContext.Provider>

library/lib/constants.ts

@@ -166,6 +166,10 @@ export const EDGES = Object.freeze({
   STEP_BORDER_RADIUS: 0,
   /** Width of the invisible stroke used for edge selection/highlighting */
   EDGE_HIGHLIGHT_STROKE_WIDTH: 15,
+  /** Height of the line-jump bridge used when edges cross */
+  EDGE_LINE_JUMP_HEIGHT: 10,
+  /** Length of the line-jump bridge along the crossed segment */
+  EDGE_LINE_JUMP_WIDTH: 16,
   /** Stub length locked to node, matches getSmoothStepPath offset */
   STUB_LENGTH: 30,
   /** Minimum total edge length (screen px) for the endpoint reconnect handles

library/lib/hooks/useEdgeLineJumps.ts

@@ -0,0 +1,97 @@
+import { useEffect, useMemo } from "react"
+import { EDGES } from "@/constants"
+import { useEdgeGeometryStore } from "@/store/context"
+import { IPoint, pointsToSvgPath } from "../edges/Connection"
+import {
+  LineJumpHit,
+  buildPathWithLineJumps,
+  computeLineJumpsForEdge,
+} from "@/utils/edgeUtils"
+
+const pointsKey = (points: IPoint[]): string =>
+  points.map((point) => `${point.x.toFixed(3)},${point.y.toFixed(3)}`).join("|")
+
+/**
+ * Publishes this edge's actual rendered (jump-free) polyline to the shared
+ * geometry registry so other edges can bridge over it at its real position,
+ * and removes it on unmount. `points` should be the edge's live render
+ * geometry (`renderPoints` for step edges, source/target for straight ones).
+ */
+export function usePublishEdgeGeometry(
+  id: string | undefined,
+  points: IPoint[]
+): void {
+  const publish = useEdgeGeometryStore((state) => state.publishEdgeGeometry)
+  const remove = useEdgeGeometryStore((state) => state.removeEdgeGeometry)
+  const key = pointsKey(points)
+
+  useEffect(() => {
+    if (id) publish(id, points)
+    // points is captured via the stable `key`; publishing is idempotent.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [id, key, publish])
+
+  useEffect(() => {
+    return () => {
+      if (id) remove(id)
+    }
+  }, [id, remove])
+}
+
+/**
+ * Returns where this edge should bridge over the edges it crosses, using the
+ * stable horizontal-hops-vertical convention (see `computeLineJumpsForEdge`).
+ * Other edges' geometry is read from the shared registry (their actual rendered
+ * points), so a bridge always centers on the crossing the user sees. Pass
+ * `enabled: false` to skip the scan (e.g. while reconnecting).
+ *
+ * Shared by both `useStepPathEdge` and `useStraightPathEdge`; the only
+ * difference between them is the `basePoints` they feed in.
+ */
+export function useEdgeLineJumps(
+  id: string | undefined,
+  basePoints: IPoint[],
+  enabled: boolean
+): LineJumpHit[] {
+  const geometryById = useEdgeGeometryStore((state) => state.geometryById)
+  const baseKey = pointsKey(basePoints)
+
+  return useMemo(() => {
+    if (!enabled || !id) return []
+    const geometryMap = new Map<string, IPoint[]>(Object.entries(geometryById))
+    const edges = Object.keys(geometryById).map((edgeId) => ({ id: edgeId }))
+    return computeLineJumpsForEdge(id, basePoints, edges, geometryMap)
+    // basePoints is captured via the stable baseKey string.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, id, baseKey, geometryById])
+}
+
+/**
+ * Builds the SVG path for an edge, drawing bridge arcs at the given crossings.
+ * Falls back to a plain polyline when there are no jumps.
+ */
+export function buildEdgePath(
+  points: IPoint[],
+  lineJumps: LineJumpHit[]
+): string {
+  if (lineJumps.length === 0) return pointsToSvgPath(points)
+
+  // Different "other" edges can report the same crossing; collapse duplicates
+  // (by segment + whole-pixel point) so only one arc is drawn per crossing.
+  const seen = new Set<string>()
+  const uniqueJumps = lineJumps.filter((jump) => {
+    const key = `${jump.segmentIndex}:${Math.round(jump.point.x)}:${Math.round(
+      jump.point.y
+    )}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+
+  return buildPathWithLineJumps(
+    points,
+    uniqueJumps,
+    EDGES.EDGE_LINE_JUMP_HEIGHT,
+    EDGES.EDGE_LINE_JUMP_WIDTH
+  )
+}

library/lib/hooks/useStepPathEdge.ts

@@ -40,6 +40,11 @@ import {
 } from "@/utils/geometry/bendHandles"
 import { useEdgeState } from "../edges/GenericEdge"
 import { useDiagramModifiable } from "./useDiagramModifiable"
+import {
+  useEdgeLineJumps,
+  usePublishEdgeGeometry,
+  buildEdgePath,
+} from "./useEdgeLineJumps"
 
 interface UseStepPathEdgeProps {
   id: string
@@ -344,9 +349,19 @@ export const useStepPathEdge = ({
   // so a live preview never leaks into the store mid-drag.
   const renderPoints = dragPreviewPoints ?? activePoints
 
-  const currentPath = useMemo(() => {
-    return pointsToSvgPath(renderPoints)
-  }, [renderPoints])
+  // Bridge over edges this one crosses. Computed from `renderPoints` so the
+  // arcs follow a live bend drag frame-by-frame (during a bend only THIS edge's
+  // points change, so only its own scan re-runs — cheap). Suppressed only while
+  // reconnecting, where the preview is drawn separately by ReconnectConnectionLine.
+  // Publish this edge's real geometry so other edges bridge over it accurately;
+  // read others' geometry to bridge over them.
+  usePublishEdgeGeometry(id, renderPoints)
+  const lineJumps = useEdgeLineJumps(id, renderPoints, !isReconnecting)
+
+  const currentPath = useMemo(
+    () => buildEdgePath(renderPoints, lineJumps),
+    [renderPoints, lineJumps]
+  )
 
   const markerSegmentPath = useMemo(
     () => getMarkerSegmentPath(renderPoints, offset, targetPosition),

library/lib/hooks/useStraightPathEdge.ts

@@ -17,6 +17,11 @@ import {
   isLengthEditableAtZoom,
 } from "@/utils/geometry/bendHandles"
 import { useMetadataStore } from "@/store/context"
+import {
+  useEdgeLineJumps,
+  usePublishEdgeGeometry,
+  buildEdgePath,
+} from "./useEdgeLineJumps"
 
 export interface StraightPathEdgeData {
   pathMiddlePosition: IPoint
@@ -69,6 +74,36 @@ export const useStraightPathEdge = ({
     EDGES.SOURCE_CONNECTION_POINT_PADDING
   )
 
+  const basePoints = useMemo<IPoint[]>(
+    () => [
+      {
+        x: adjustedSourceCoordinates.sourceX,
+        y: adjustedSourceCoordinates.sourceY,
+      },
+      {
+        x: adjustedTargetCoordinates.targetX,
+        y: adjustedTargetCoordinates.targetY,
+      },
+    ],
+    [
+      adjustedSourceCoordinates.sourceX,
+      adjustedSourceCoordinates.sourceY,
+      adjustedTargetCoordinates.targetX,
+      adjustedTargetCoordinates.targetY,
+    ]
+  )
+
+  // Publish this edge's real geometry so other edges bridge over it accurately.
+  usePublishEdgeGeometry(id, basePoints)
+
+  // UseCase include/extend edges are dashed connectors that never read as
+  // crossings to disambiguate, so they opt out of bridging.
+  const lineJumps = useEdgeLineJumps(
+    id,
+    basePoints,
+    !isReconnecting && type !== "UseCaseInclude" && type !== "UseCaseExtend"
+  )
+
   const [pathMiddlePosition, setPathMiddlePosition] = useState<IPoint>(() => ({
     x:
       (adjustedSourceCoordinates.sourceX + adjustedTargetCoordinates.targetX) /
@@ -90,6 +125,7 @@ export const useStraightPathEdge = ({
   )
 
   const currentPath = useMemo(() => {
+    if (lineJumps.length > 0) return buildEdgePath(basePoints, lineJumps)
     return calculateStraightPath(
       adjustedSourceCoordinates.sourceX,
       adjustedSourceCoordinates.sourceY,
@@ -103,10 +139,14 @@ export const useStraightPathEdge = ({
     adjustedTargetCoordinates.targetX,
     adjustedTargetCoordinates.targetY,
     type,
-    targetPosition,
+    basePoints,
+    lineJumps,
   ])
 
   const overlayPath = useMemo(() => {
+    // When bridging, the arc'd path is the hit target too, so the selectable
+    // stroke matches exactly what's drawn.
+    if (lineJumps.length > 0) return currentPath
     return calculateOverlayPath(
       adjustedSourceCoordinates.sourceX,
       adjustedSourceCoordinates.sourceY,
@@ -120,7 +160,8 @@ export const useStraightPathEdge = ({
     adjustedTargetCoordinates.targetX,
     adjustedTargetCoordinates.targetY,
     type,
-    targetPosition,
+    currentPath,
+    lineJumps,
   ])
 
   useEffect(() => {
@@ -205,14 +246,7 @@ export const useStraightPathEdge = ({
     adjustedTargetCoordinates.targetY,
   ])
 
-  const sourcePoint = {
-    x: adjustedSourceCoordinates.sourceX,
-    y: adjustedSourceCoordinates.sourceY,
-  }
-  const targetPoint = {
-    x: adjustedTargetCoordinates.targetX,
-    y: adjustedTargetCoordinates.targetY,
-  }
+  const [sourcePoint, targetPoint] = basePoints
   const canvasLength = Math.hypot(
     targetPoint.x - sourcePoint.x,
     targetPoint.y - sourcePoint.y

library/lib/store/context.ts

@@ -5,6 +5,7 @@ import { MetadataStore } from "./metadataStore"
 import { PopoverStore } from "./popoverStore"
 import { AssessmentSelectionStore } from "./assessmentSelectionStore"
 import { AlignmentGuidesStore } from "./alignmentGuidesStore"
+import { EdgeGeometryStore } from "./edgeGeometryStore"
 
 export const DiagramStoreContext = createContext<StoreApi<DiagramStore> | null>(
   null
@@ -23,6 +24,9 @@ export const AssessmentSelectionStoreContext =
 export const AlignmentGuidesStoreContext =
   createContext<StoreApi<AlignmentGuidesStore> | null>(null)
 
+export const EdgeGeometryStoreContext =
+  createContext<StoreApi<EdgeGeometryStore> | null>(null)
+
 // Custom hooks for components
 export const useDiagramStore = <T>(selector: (state: DiagramStore) => T): T => {
   const store = useContext(DiagramStoreContext)
@@ -59,3 +63,11 @@ export const useAlignmentGuidesStore = <T>(
   if (!store) throw new Error("AlignmentGuidesStoreContext not provided")
   return useStore(store, selector)
 }
+
+export const useEdgeGeometryStore = <T>(
+  selector: (state: EdgeGeometryStore) => T
+): T => {
+  const store = useContext(EdgeGeometryStoreContext)
+  if (!store) throw new Error("EdgeGeometryStoreContext not provided")
+  return useStore(store, selector)
+}