@graph-artifact/core 0.1.0

package/dist/layout/edges/buildEdges.js

@@ -0,0 +1,405 @@
+/**
+ * buildEdges.ts — Main edge builder.
+ *
+ * Orchestrates: intersection → path generation → handle assignment → styling
+ * to produce React Flow Edge objects from parsed edges + dagre waypoints.
+ *
+ * For each edge:
+ *   1. Takes dagre's waypoints (which route around intermediate nodes)
+ *   2. Computes node-boundary intersection (rect or diamond) for start/end
+ *   3. Shortens the end by the arrow marker size so the tip lands at the boundary
+ *   4. Generates a rounded SVG path through all waypoints
+ *   5. Passes the pre-computed path + label position as edge data
+ */
+import { MarkerType } from '@xyflow/react';
+import { intersectNode } from '../intersect/index.js';
+import { waypointsDeviate, shortenPathEnd, shortenPathStart, generateSmoothPath, generateRoundedPath, computeLabelPosition, } from './paths.js';
+import { classifyEdge, edgeStyleForType } from './classify.js';
+// ─── Constants ──────────────────────────────────────────────────────────────
+const MARKER_SHORTENING = 6; // shorten path end so arrowhead tip sits at the boundary
+const ER_PATH_GAP = 8; // hard visual clearance from ER node boundary
+function clamp255(v) {
+    return Math.max(0, Math.min(255, Math.round(v)));
+}
+function shadeHex(hex, factor) {
+    const clean = hex.replace('#', '');
+    if (!/^[0-9a-fA-F]{6}$/.test(clean))
+        return hex;
+    const r = parseInt(clean.slice(0, 2), 16);
+    const g = parseInt(clean.slice(2, 4), 16);
+    const b = parseInt(clean.slice(4, 6), 16);
+    const rr = clamp255(r * (1 + factor));
+    const gg = clamp255(g * (1 + factor));
+    const bb = clamp255(b * (1 + factor));
+    return `#${rr.toString(16).padStart(2, '0')}${gg.toString(16).padStart(2, '0')}${bb.toString(16).padStart(2, '0')}`;
+}
+function buildBranchPalette(base, orange2, orange3) {
+    return [
+        shadeHex(base, -0.22),
+        shadeHex(base, -0.12),
+        base,
+        orange2,
+        orange3,
+        shadeHex(base, 0.14),
+    ];
+}
+function pushOutFromNodeBoundary(point, node, distance) {
+    if (distance <= 0)
+        return point;
+    const dx = point.x - node.x;
+    const dy = point.y - node.y;
+    const len = Math.hypot(dx, dy);
+    if (len < 1e-6)
+        return point;
+    return {
+        x: point.x + (dx / len) * distance,
+        y: point.y + (dy / len) * distance,
+    };
+}
+function clampErEndpoints(points, sourceCenter, targetCenter, sourceShape, targetShape, borderRadius, gap) {
+    if (points.length < 2)
+        return points;
+    const out = points.slice();
+    const startRef = out[1];
+    const endRef = out[out.length - 2];
+    const startBoundary = intersectNode(sourceCenter, startRef, sourceShape, borderRadius);
+    const endBoundary = intersectNode(targetCenter, endRef, targetShape, borderRadius);
+    out[0] = pushOutFromNodeBoundary(startBoundary, sourceCenter, gap);
+    out[out.length - 1] = pushOutFromNodeBoundary(endBoundary, targetCenter, gap);
+    return out;
+}
+function pointInsideNodeBounds(point, node, epsilon = 0.5) {
+    const left = node.x - node.width / 2;
+    const right = node.x + node.width / 2;
+    const top = node.y - node.height / 2;
+    const bottom = node.y + node.height / 2;
+    return (point.x >= left - epsilon &&
+        point.x <= right + epsilon &&
+        point.y >= top - epsilon &&
+        point.y <= bottom + epsilon);
+}
+function chooseSourceAimPoint(center, points) {
+    const first = points[0];
+    if (!first || points.length < 2)
+        return first;
+    const second = points[1];
+    const dx = first.x - center.x;
+    const dy = first.y - center.y;
+    const turnDx = second.x - first.x;
+    const turnDy = second.y - first.y;
+    // If dagre creates a short vertical exit then quickly turns lateral,
+    // prefer the lateral point so the edge exits from the side when appropriate.
+    const verticalThenLateral = Math.abs(dx) < 6 &&
+        Math.abs(dy) > 6 &&
+        Math.abs(turnDx) > Math.abs(turnDy) * 1.25;
+    return verticalThenLateral ? second : first;
+}
+function chooseTargetAimPoint(center, points) {
+    const last = points[points.length - 1];
+    if (!last || points.length < 2)
+        return last;
+    const prev = points[points.length - 2];
+    const dx = last.x - center.x;
+    const dy = last.y - center.y;
+    const turnDx = last.x - prev.x;
+    const turnDy = last.y - prev.y;
+    const lateralThenVerticalNearTarget = Math.abs(dx) < 6 &&
+        Math.abs(dy) > 6 &&
+        Math.abs(turnDx) > Math.abs(turnDy) * 1.25;
+    return lateralThenVerticalNearTarget ? prev : last;
+}
+// ─── Edge Builder ───────────────────────────────────────────────────────────
+export function buildEdges(parsedEdges, positions, _handles, direction, theme, diamondEdgeHandles, edgeWaypoints, nodeShapes) {
+    const markerSize = theme.edgeDefaults.markerSize;
+    const isVertical = direction === 'TB' || direction === 'BT';
+    const cardBorderRadius = parseInt(theme.radius.lg, 10) || 8;
+    const branchPalette = buildBranchPalette(theme.color.orange1, theme.color.orange2, theme.color.orange3);
+    // Build handle slot maps for forward edges
+    const forwardBySource = new Map();
+    const forwardByTarget = new Map();
+    parsedEdges.forEach((edge, i) => {
+        const sp = positions.get(edge.source);
+        const tp = positions.get(edge.target);
+        if (!sp || !tp)
+            return;
+        const edgeClass = classifyEdge(sp, tp, direction);
+        if (edgeClass !== 'forward')
+            return;
+        const targetCross = isVertical ? tp.x + tp.width / 2 : tp.y + tp.height / 2;
+        const sourceCross = isVertical ? sp.x + sp.width / 2 : sp.y + sp.height / 2;
+        const srcGroup = forwardBySource.get(edge.source) ?? [];
+        srcGroup.push({ edgeIndex: i, otherPos: targetCross });
+        forwardBySource.set(edge.source, srcGroup);
+        const tgtGroup = forwardByTarget.get(edge.target) ?? [];
+        tgtGroup.push({ edgeIndex: i, otherPos: sourceCross });
+        forwardByTarget.set(edge.target, tgtGroup);
+    });
+    const fwSourceSlot = new Map();
+    const fwTargetSlot = new Map();
+    for (const [, group] of forwardBySource) {
+        group.sort((a, b) => a.otherPos - b.otherPos);
+        group.forEach((entry, slot) => fwSourceSlot.set(entry.edgeIndex, slot));
+    }
+    for (const [, group] of forwardByTarget) {
+        group.sort((a, b) => a.otherPos - b.otherPos);
+        group.forEach((entry, slot) => fwTargetSlot.set(entry.edgeIndex, slot));
+    }
+    // Back-edge side handle counters
+    const SIDE_SLOTS = 5;
+    const backSourceCounters = new Map();
+    const backTargetCounters = new Map();
+    return parsedEdges.map((edge, i) => {
+        const sourcePos = positions.get(edge.source);
+        const targetPos = positions.get(edge.target);
+        const edgeClass = sourcePos && targetPos
+            ? classifyEdge(sourcePos, targetPos, direction)
+            : 'forward';
+        const waypoints = edgeWaypoints?.[i];
+        const sourceShape = nodeShapes?.get(edge.source) ?? 'rect';
+        const targetShape = nodeShapes?.get(edge.target) ?? 'rect';
+        // ── Compute path from dagre waypoints ──
+        let svgPath = '';
+        let labelPos = { x: 0, y: 0 };
+        // ER edges draw cardinality symbols manually (no SVG markers),
+        // so no path shortening needed.
+        const isErEdge = edge.cardSource || edge.cardTarget;
+        const isMindmapEdge = !!edge.noArrow;
+        const shortenEnd = isErEdge ? ER_PATH_GAP : (isMindmapEdge ? 0 : MARKER_SHORTENING);
+        const shortenStart = isErEdge ? ER_PATH_GAP : 0;
+        // Track path endpoints + angles for ER cardinality symbols
+        let pathStart;
+        let pathEnd;
+        let startAngle = 0; // angle toward source node (radians)
+        let endAngle = 0; // angle toward target node (radians)
+        let routePointsForLive;
+        if (waypoints && waypoints.points.length > 0 && sourcePos && targetPos) {
+            const sourceCenter = {
+                x: sourcePos.x + sourcePos.width / 2,
+                y: sourcePos.y + sourcePos.height / 2,
+                width: sourcePos.width,
+                height: sourcePos.height,
+            };
+            const targetCenter = {
+                x: targetPos.x + targetPos.width / 2,
+                y: targetPos.y + targetPos.height / 2,
+                width: targetPos.width,
+                height: targetPos.height,
+            };
+            const rawPoints = waypoints.points;
+            // Determine if dagre's waypoints deviate from a straight source→target line.
+            // Back/lateral edges always use waypoints (they need routing to avoid overlap).
+            // Forward edges use waypoints only if they deviate significantly from straight.
+            // For ER, always keep dagre waypoint routing so curves stay natural.
+            // The straight-forward shortcut makes ER edges look too angular.
+            const isSimpleForward = !isErEdge && !edge.noArrow && edgeClass === 'forward' && !waypointsDeviate(rawPoints, 20);
+            if (isSimpleForward) {
+                // Simple forward edge: straight line from source boundary to target boundary.
+                const startIntersect = intersectNode(sourceCenter, targetCenter, sourceShape, isErEdge ? cardBorderRadius : 0);
+                const endIntersect = intersectNode(targetCenter, sourceCenter, targetShape, isErEdge ? cardBorderRadius : 0);
+                let finalPoints = [startIntersect, endIntersect];
+                finalPoints = shortenPathStart(finalPoints, shortenStart);
+                finalPoints = shortenPathEnd(finalPoints, shortenEnd);
+                if (isErEdge) {
+                    finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, ER_PATH_GAP);
+                }
+                labelPos = computeLabelPosition(finalPoints);
+                svgPath = `M${finalPoints[0].x},${finalPoints[0].y}L${finalPoints[1].x},${finalPoints[1].y}`;
+                routePointsForLive = finalPoints;
+                // Compute endpoint angles for ER cardinality symbols
+                pathStart = finalPoints[0];
+                pathEnd = finalPoints[finalPoints.length - 1];
+                // Start angle: toward source node (from second point back to first)
+                startAngle = Math.atan2(finalPoints[0].y - finalPoints[1].y, finalPoints[0].x - finalPoints[1].x);
+                // End angle: toward target node (from second-to-last to last)
+                endAngle = Math.atan2(finalPoints[finalPoints.length - 1].y - finalPoints[finalPoints.length - 2].y, finalPoints[finalPoints.length - 1].x - finalPoints[finalPoints.length - 2].x);
+            }
+            else {
+                // Complex route: strip first/last (node centers), keep inner routing points.
+                const innerPoints = rawPoints.length > 2
+                    ? rawPoints.slice(1, -1)
+                    : rawPoints.slice();
+                // Dagre waypoints are based on estimated node sizes. After React Flow
+                // measurement, ER/Class nodes can be taller; trim any near-end waypoints
+                // that now fall inside source/target node bounds to prevent edge overlap.
+                while (innerPoints.length > 0 && pointInsideNodeBounds(innerPoints[0], sourceCenter)) {
+                    innerPoints.shift();
+                }
+                while (innerPoints.length > 0 && pointInsideNodeBounds(innerPoints[innerPoints.length - 1], targetCenter)) {
+                    innerPoints.pop();
+                }
+                if (innerPoints.length === 0) {
+                    const startIntersect = intersectNode(sourceCenter, targetCenter, sourceShape, isErEdge ? cardBorderRadius : 0);
+                    const endIntersect = intersectNode(targetCenter, sourceCenter, targetShape, isErEdge ? cardBorderRadius : 0);
+                    let finalPoints = [startIntersect, endIntersect];
+                    finalPoints = shortenPathStart(finalPoints, shortenStart);
+                    finalPoints = shortenPathEnd(finalPoints, shortenEnd);
+                    if (isErEdge) {
+                        finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, ER_PATH_GAP);
+                    }
+                    labelPos = computeLabelPosition(finalPoints);
+                    svgPath = `M${finalPoints[0].x},${finalPoints[0].y}L${finalPoints[1].x},${finalPoints[1].y}`;
+                    routePointsForLive = finalPoints;
+                    pathStart = finalPoints[0];
+                    pathEnd = finalPoints[finalPoints.length - 1];
+                    startAngle = Math.atan2(finalPoints[0].y - finalPoints[1].y, finalPoints[0].x - finalPoints[1].x);
+                    endAngle = Math.atan2(finalPoints[finalPoints.length - 1].y - finalPoints[finalPoints.length - 2].y, finalPoints[finalPoints.length - 1].x - finalPoints[finalPoints.length - 2].x);
+                }
+                else {
+                    const sourceAim = isErEdge ? chooseSourceAimPoint(sourceCenter, innerPoints) : innerPoints[0];
+                    const targetAim = isErEdge ? chooseTargetAimPoint(targetCenter, innerPoints) : innerPoints[innerPoints.length - 1];
+                    const startIntersect = intersectNode(sourceCenter, sourceAim, sourceShape, isErEdge ? cardBorderRadius : 0);
+                    const endIntersect = intersectNode(targetCenter, targetAim, targetShape, isErEdge ? cardBorderRadius : 0);
+                    let finalPoints = [startIntersect, ...innerPoints, endIntersect];
+                    finalPoints = shortenPathStart(finalPoints, shortenStart);
+                    finalPoints = shortenPathEnd(finalPoints, shortenEnd);
+                    if (isErEdge) {
+                        finalPoints = clampErEndpoints(finalPoints, sourceCenter, targetCenter, sourceShape, targetShape, cardBorderRadius, ER_PATH_GAP);
+                    }
+                    labelPos = computeLabelPosition(finalPoints);
+                    // For ER, keep middle smoothing but force straight start/end segments.
+                    // This stabilizes endpoint tangent (for cardinality symbols) and
+                    // prevents spline overshoot from visually re-entering node bounds.
+                    if (edge.noArrow) {
+                        if (finalPoints.length === 3) {
+                            const [p0, c, p2] = finalPoints;
+                            svgPath = `M${p0.x},${p0.y}Q${c.x},${c.y},${p2.x},${p2.y}`;
+                        }
+                        else {
+                            svgPath = generateRoundedPath(finalPoints, 24);
+                        }
+                    }
+                    else {
+                        svgPath = generateSmoothPath(finalPoints, !!isErEdge);
+                    }
+                    routePointsForLive = finalPoints;
+                    // Compute endpoint angles for ER cardinality symbols
+                    pathStart = finalPoints[0];
+                    pathEnd = finalPoints[finalPoints.length - 1];
+                    startAngle = Math.atan2(finalPoints[0].y - finalPoints[1].y, finalPoints[0].x - finalPoints[1].x);
+                    endAngle = Math.atan2(finalPoints[finalPoints.length - 1].y - finalPoints[finalPoints.length - 2].y, finalPoints[finalPoints.length - 1].x - finalPoints[finalPoints.length - 2].x);
+                }
+            }
+        }
+        // ── Handle assignment ──
+        let sourceHandle;
+        let targetHandle;
+        if (isErEdge && sourcePos && targetPos) {
+            // ER-specific handle strategy:
+            // prefer side handles for lateral/diagonal links, top/bottom for vertical links.
+            const srcCX = sourcePos.x + sourcePos.width / 2;
+            const srcCY = sourcePos.y + sourcePos.height / 2;
+            const tgtCX = targetPos.x + targetPos.width / 2;
+            const tgtCY = targetPos.y + targetPos.height / 2;
+            const dx = tgtCX - srcCX;
+            const dy = tgtCY - srcCY;
+            const lateralBias = Math.abs(dx) > Math.abs(dy) * 0.55;
+            if (lateralBias) {
+                const srcSide = dx >= 0 ? 'right' : 'left';
+                const tgtSide = dx >= 0 ? 'left' : 'right';
+                const midSlot = 2; // center of 5 slots
+                sourceHandle = `back-${srcSide}-source-${midSlot}`;
+                targetHandle = `back-${tgtSide}-target-${midSlot}`;
+            }
+            else {
+                // Vertical ER links use canonical forward handles.
+                sourceHandle = 'fw-source-0';
+                targetHandle = 'fw-target-0';
+            }
+        }
+        else if (edgeClass === 'back') {
+            const srcCX = sourcePos ? sourcePos.x + sourcePos.width / 2 : 0;
+            const tgtCX = targetPos ? targetPos.x + targetPos.width / 2 : 0;
+            const side = srcCX <= tgtCX ? 'left' : 'right';
+            const srcKey = `${edge.source}:${side}`;
+            const tgtKey = `${edge.target}:${side}`;
+            const srcSlot = (backSourceCounters.get(srcKey) ?? 0) % SIDE_SLOTS;
+            const tgtSlot = (backTargetCounters.get(tgtKey) ?? 0) % SIDE_SLOTS;
+            backSourceCounters.set(srcKey, srcSlot + 1);
+            backTargetCounters.set(tgtKey, tgtSlot + 1);
+            sourceHandle = `back-${side}-source-${srcSlot}`;
+            targetHandle = `back-${side}-target-${tgtSlot}`;
+        }
+        else if (edgeClass === 'lateral') {
+            sourceHandle = 'lateral-source';
+            targetHandle = 'lateral-target';
+        }
+        else {
+            const diamondHandle = diamondEdgeHandles?.get(i);
+            if (diamondHandle) {
+                sourceHandle = diamondHandle;
+            }
+            else {
+                const srcGroup = forwardBySource.get(edge.source);
+                const srcSlot = fwSourceSlot.get(i);
+                if (srcGroup && srcGroup.length > 1 && srcSlot !== undefined) {
+                    sourceHandle = `fw-source-${srcSlot}`;
+                }
+            }
+            const tgtGroup = forwardByTarget.get(edge.target);
+            const tgtSlot = fwTargetSlot.get(i);
+            if (tgtGroup && tgtGroup.length > 1 && tgtSlot !== undefined) {
+                targetHandle = `fw-target-${tgtSlot}`;
+            }
+        }
+        // ER edges use cardinality markers instead of arrowheads
+        const hasCardinality = edge.cardSource || edge.cardTarget;
+        const disableArrowMarker = hasCardinality || edge.noArrow;
+        const baseStyle = edgeStyleForType(edge.edgeType, theme);
+        const mindmapStyle = edge.noArrow
+            ? {
+                ...baseStyle,
+                stroke: branchPalette[Math.abs(edge.branchIndex ?? 0) % branchPalette.length],
+                strokeWidth: (edge.treeDepth ?? 2) <= 1
+                    ? 6
+                    : (edge.treeDepth ?? 2) === 2
+                        ? 3.5
+                        : 2.25,
+                opacity: 0.92,
+            }
+            : baseStyle;
+        return {
+            id: `e-${edge.source}-${edge.target}-${i}`,
+            source: edge.source,
+            target: edge.target,
+            label: edge.label,
+            type: 'routed',
+            animated: false,
+            style: mindmapStyle,
+            labelStyle: theme.edgeDefaults.labelStyle,
+            labelBgStyle: theme.edgeDefaults.labelBgStyle,
+            labelBgPadding: theme.edgeDefaults.labelBgPadding,
+            labelBgBorderRadius: theme.edgeDefaults.labelBgBorderRadius,
+            sourceHandle,
+            targetHandle,
+            zIndex: isErEdge ? 2 : (edgeClass === 'back' ? 0 : 1),
+            data: {
+                svgPath,
+                labelX: labelPos.x,
+                labelY: labelPos.y,
+                bgColor: theme.color.darkBg2,
+                cardSource: edge.cardSource,
+                cardTarget: edge.cardTarget,
+                cardSourceToken: edge.cardSourceToken,
+                cardTargetToken: edge.cardTargetToken,
+                ...(isErEdge && routePointsForLive ? { routePoints: routePointsForLive } : {}),
+                // Endpoint data for manual cardinality symbol rendering
+                ...(isErEdge && pathStart && pathEnd ? {
+                    pathStartX: pathStart.x,
+                    pathStartY: pathStart.y,
+                    pathStartAngle: startAngle,
+                    pathEndX: pathEnd.x,
+                    pathEndY: pathEnd.y,
+                    pathEndAngle: endAngle,
+                } : {}),
+            },
+            ...(disableArrowMarker ? {} : {
+                markerEnd: {
+                    type: MarkerType.ArrowClosed,
+                    color: theme.color.gray3,
+                    width: markerSize,
+                    height: markerSize,
+                },
+            }),
+        };
+    });
+}

package/dist/layout/edges/classify.d.ts

@@ -0,0 +1,13 @@
+/**
+ * classify.ts — Edge classification and styling.
+ *
+ * Determines whether an edge is forward, back, or lateral based on
+ * node positions and graph direction. Also resolves edge visual styles
+ * (solid, dashed, thick) from theme tokens.
+ */
+import type { ParsedGraph, EdgeType } from '../../types.js';
+import type { Theme } from '../../ThemeContext.js';
+import type { NodePosition } from '../types.js';
+export type EdgeDirection = 'forward' | 'back' | 'lateral';
+export declare function classifyEdge(sourcePos: NodePosition, targetPos: NodePosition, direction: ParsedGraph['direction']): EdgeDirection;
+export declare function edgeStyleForType(edgeType: EdgeType | undefined, theme: Theme): Record<string, unknown>;

package/dist/layout/edges/classify.js

@@ -0,0 +1,36 @@
+/**
+ * classify.ts — Edge classification and styling.
+ *
+ * Determines whether an edge is forward, back, or lateral based on
+ * node positions and graph direction. Also resolves edge visual styles
+ * (solid, dashed, thick) from theme tokens.
+ */
+export function classifyEdge(sourcePos, targetPos, direction) {
+    const sourceCenterY = sourcePos.y + sourcePos.height / 2;
+    const targetCenterY = targetPos.y + targetPos.height / 2;
+    const sourceCenterX = sourcePos.x + sourcePos.width / 2;
+    const targetCenterX = targetPos.x + targetPos.width / 2;
+    const isVertical = direction === 'TB' || direction === 'BT';
+    const primaryDelta = isVertical
+        ? targetCenterY - sourceCenterY
+        : targetCenterX - sourceCenterX;
+    const threshold = isVertical
+        ? (sourcePos.height + targetPos.height) / 4
+        : (sourcePos.width + targetPos.width) / 4;
+    if (Math.abs(primaryDelta) < threshold)
+        return 'lateral';
+    const isForwardDirection = direction === 'TB' || direction === 'LR';
+    return (primaryDelta > 0) === isForwardDirection ? 'forward' : 'back';
+}
+// ─── Edge Styling ───────────────────────────────────────────────────────────
+export function edgeStyleForType(edgeType, theme) {
+    const base = theme.edgeDefaults.style;
+    switch (edgeType) {
+        case 'dashed':
+            return { ...base, strokeDasharray: theme.edgeDefaults.dashedPattern };
+        case 'thick':
+            return { ...base, strokeWidth: theme.edgeDefaults.thickWidth };
+        default:
+            return base;
+    }
+}

package/dist/layout/edges/diamondHandles.d.ts

@@ -0,0 +1,23 @@
+/**
+ * diamondHandles.ts — Diamond handle configuration and forward edge counting.
+ *
+ * Computes how many source handles a diamond node needs at each position
+ * (bottom, left, right) based on where each outgoing edge's target is
+ * located relative to the diamond center. Also counts forward-edge
+ * connections per node for handle spreading.
+ */
+import type { ParsedEdge, ParsedGraph, ParsedNode } from '../../types.js';
+import type { NodePosition } from '../types.js';
+export interface DiamondHandleConfig {
+    bottom: number;
+    left: number;
+    right: number;
+}
+export declare function computeDiamondAssignments(nodes: ParsedNode[], parsedEdges: ParsedEdge[], positions: Map<string, NodePosition>, direction: ParsedGraph['direction']): {
+    handleConfigs: Map<string, DiamondHandleConfig>;
+    edgeHandles: Map<number, string>;
+};
+export declare function computeForwardEdgeCounts(parsedEdges: ParsedEdge[], positions: Map<string, NodePosition>, direction: ParsedGraph['direction']): {
+    incoming: Map<string, number>;
+    outgoing: Map<string, number>;
+};

package/dist/layout/edges/diamondHandles.js

@@ -0,0 +1,108 @@
+/**
+ * diamondHandles.ts — Diamond handle configuration and forward edge counting.
+ *
+ * Computes how many source handles a diamond node needs at each position
+ * (bottom, left, right) based on where each outgoing edge's target is
+ * located relative to the diamond center. Also counts forward-edge
+ * connections per node for handle spreading.
+ */
+import { classifyEdge } from './classify.js';
+export function computeDiamondAssignments(nodes, parsedEdges, positions, direction) {
+    const handleConfigs = new Map();
+    const edgeHandles = new Map();
+    const isVertical = direction === 'TB' || direction === 'BT';
+    const diamondIds = new Set();
+    for (const node of nodes) {
+        if (node.shape === 'diamond')
+            diamondIds.add(node.id);
+    }
+    if (diamondIds.size === 0)
+        return { handleConfigs, edgeHandles };
+    const outgoingByDiamond = new Map();
+    parsedEdges.forEach((edge, i) => {
+        if (!diamondIds.has(edge.source))
+            return;
+        const sp = positions.get(edge.source);
+        const tp = positions.get(edge.target);
+        if (!sp || !tp)
+            return;
+        const edgeClass = classifyEdge(sp, tp, direction);
+        if (edgeClass !== 'forward')
+            return;
+        const group = outgoingByDiamond.get(edge.source) ?? [];
+        group.push({ edgeIndex: i, targetId: edge.target });
+        outgoingByDiamond.set(edge.source, group);
+    });
+    for (const [diamondId, outgoing] of outgoingByDiamond) {
+        const diamondPos = positions.get(diamondId);
+        const diamondCX = diamondPos.x + diamondPos.width / 2;
+        const diamondCY = diamondPos.y + diamondPos.height / 2;
+        const threshold = diamondPos.width * 0.3;
+        const classified = [];
+        for (const { edgeIndex, targetId } of outgoing) {
+            const targetPos = positions.get(targetId);
+            const targetCX = targetPos.x + targetPos.width / 2;
+            const targetCY = targetPos.y + targetPos.height / 2;
+            let position;
+            const relativeX = targetCX - diamondCX;
+            if (isVertical) {
+                const isBelow = targetCY > diamondCY;
+                if (isBelow && Math.abs(relativeX) <= threshold) {
+                    position = 'bottom';
+                }
+                else if (relativeX < 0) {
+                    position = 'left';
+                }
+                else {
+                    position = 'right';
+                }
+            }
+            else {
+                const relativeY = targetCY - diamondCY;
+                const isForward = direction === 'LR' ? targetCX > diamondCX : targetCX < diamondCX;
+                if (isForward && Math.abs(relativeY) <= threshold) {
+                    position = 'bottom';
+                }
+                else if (relativeY < 0) {
+                    position = 'left';
+                }
+                else {
+                    position = 'right';
+                }
+            }
+            classified.push({ edgeIndex, relativeX, position });
+        }
+        const bottomEdges = classified.filter(c => c.position === 'bottom');
+        if (bottomEdges.length > 1) {
+            bottomEdges.sort((a, b) => Math.abs(a.relativeX) - Math.abs(b.relativeX));
+            for (let i = 1; i < bottomEdges.length; i++) {
+                bottomEdges[i].position = bottomEdges[i].relativeX < 0 ? 'left' : 'right';
+            }
+        }
+        const config = { bottom: 0, left: 0, right: 0 };
+        for (const c of classified) {
+            const slot = config[c.position];
+            config[c.position]++;
+            edgeHandles.set(c.edgeIndex, `fw-source-${c.position}-${slot}`);
+        }
+        handleConfigs.set(diamondId, config);
+    }
+    return { handleConfigs, edgeHandles };
+}
+// ─── Forward Edge Counts ────────────────────────────────────────────────────
+export function computeForwardEdgeCounts(parsedEdges, positions, direction) {
+    const incoming = new Map();
+    const outgoing = new Map();
+    for (const edge of parsedEdges) {
+        const sourcePos = positions.get(edge.source);
+        const targetPos = positions.get(edge.target);
+        if (!sourcePos || !targetPos)
+            continue;
+        const edgeClass = classifyEdge(sourcePos, targetPos, direction);
+        if (edgeClass !== 'forward')
+            continue;
+        outgoing.set(edge.source, (outgoing.get(edge.source) ?? 0) + 1);
+        incoming.set(edge.target, (incoming.get(edge.target) ?? 0) + 1);
+    }
+    return { incoming, outgoing };
+}

package/dist/layout/edges/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * edges/ — Edge construction pipeline.
+ *
+ * Barrel export for all edge-related functionality.
+ */
+export { buildEdges } from './buildEdges.js';
+export { computeForwardEdgeCounts, computeDiamondAssignments } from './diamondHandles.js';
+export type { DiamondHandleConfig } from './diamondHandles.js';
+export { classifyEdge, edgeStyleForType } from './classify.js';
+export type { EdgeDirection } from './classify.js';

package/dist/layout/edges/index.js

@@ -0,0 +1,8 @@
+/**
+ * edges/ — Edge construction pipeline.
+ *
+ * Barrel export for all edge-related functionality.
+ */
+export { buildEdges } from './buildEdges.js';
+export { computeForwardEdgeCounts, computeDiamondAssignments } from './diamondHandles.js';
+export { classifyEdge, edgeStyleForType } from './classify.js';

package/dist/layout/edges/paths.d.ts

@@ -0,0 +1,57 @@
+/**
+ * paths.ts — Pure path math utilities.
+ *
+ * Functions for path generation, shortening, deviation detection,
+ * and label placement. No side effects, no DOM, no React — just geometry.
+ */
+import type { Point } from '../types.js';
+/**
+ * Checks whether any waypoint deviates from the straight line between the
+ * first and last point by more than `threshold` pixels.
+ *
+ * Used to distinguish simple straight edges (where dagre's waypoints are
+ * essentially collinear) from routed edges (where dagre bent the path
+ * around obstacles). Back-edges and lateral edges skip this check entirely.
+ */
+export declare function waypointsDeviate(points: Point[], threshold: number): boolean;
+/**
+ * Shortens a path by moving the last point `distance` pixels back along
+ * the direction from the second-to-last point to the last point.
+ * This prevents the arrowhead marker from overshooting the node boundary.
+ */
+export declare function shortenPathEnd(points: Point[], distance: number): Point[];
+/**
+ * Shortens a path by moving the first point `distance` pixels forward along
+ * the direction from the first point to the second point.
+ * Used for ER start markers so they don't overflow into the source node.
+ */
+export declare function shortenPathStart(points: Point[], distance: number): Point[];
+/**
+ * Generates an SVG path using Catmull-Rom interpolation through all points.
+ *
+ * Unlike B-splines (which approximate), Catmull-Rom passes THROUGH every
+ * control point while producing smooth curves between them. This gives us
+ * the flowing look of Mermaid's curveBasis without the overshoot problem.
+ *
+ * For edges with only 2 points (straight lines), produces a simple L command.
+ * For edges with bends, produces smooth cubic bezier curves that naturally
+ * flow through dagre's computed waypoints.
+ *
+ * When `straightEnds` is true, the first and last segments use straight lines
+ * instead of curves. This ensures markers at path endpoints align perfectly
+ * with the node boundary (used for ER cardinality markers).
+ *
+ * Alpha = 0.5 (centripetal) prevents cusps and self-intersections.
+ */
+export declare function generateSmoothPath(points: Point[], straightEnds?: boolean): string;
+/**
+ * Basis spline path (d3 curveBasis style): smoother than Catmull-Rom and
+ * naturally reduces sharp elbows in orthogonal-ish routes.
+ */
+export declare function generateBasisPath(points: Point[]): string;
+/**
+ * Generates a polyline path with rounded corners using quadratic curves.
+ * End segments stay straight; only interior corners are rounded.
+ */
+export declare function generateRoundedPath(points: Point[], radius?: number): string;
+export declare function computeLabelPosition(points: Point[]): Point;