@spectratools/graphic-designer-cli 0.9.0 → 0.11.0

package/dist/cli.js

@@ -820,6 +820,21 @@ var drawLineSchema = z2.object({
   opacity: z2.number().min(0).max(1).default(1),
   shadow: drawShadowSchema.optional()
 }).strict();
+var drawArcSchema = z2.object({
+  type: z2.literal("arc"),
+  center: z2.object({
+    x: z2.number(),
+    y: z2.number()
+  }).strict(),
+  radius: z2.number().positive(),
+  startAngle: z2.number(),
+  endAngle: z2.number(),
+  color: colorHexSchema2.default("#FFFFFF"),
+  width: z2.number().min(0.5).max(32).default(2),
+  dash: z2.array(z2.number()).max(6).optional(),
+  opacity: z2.number().min(0).max(1).default(1),
+  shadow: drawShadowSchema.optional()
+}).strict();
 var drawPointSchema = z2.object({
   x: z2.number(),
   y: z2.number()
@@ -904,6 +919,7 @@ var drawCommandSchema = z2.discriminatedUnion("type", [
   drawCircleSchema,
   drawTextSchema,
   drawLineSchema,
+  drawArcSchema,
   drawBezierSchema,
   drawPathSchema,
   drawBadgeSchema,
@@ -1034,17 +1050,21 @@ var connectionElementSchema = z2.object({
   from: z2.string().min(1).max(120),
   to: z2.string().min(1).max(120),
   style: z2.enum(["solid", "dashed", "dotted"]).default("solid"),
-  strokeStyle: z2.enum(["solid", "dashed", "dotted"]).default("solid"),
+  /** @deprecated Use `style` instead. */
+  strokeStyle: z2.enum(["solid", "dashed", "dotted"]).optional(),
   arrow: z2.enum(["end", "start", "both", "none"]).default("end"),
   label: z2.string().min(1).max(200).optional(),
   labelPosition: z2.enum(["start", "middle", "end"]).default("middle"),
   color: colorHexSchema2.optional(),
+  fromColor: colorHexSchema2.optional(),
+  toColor: colorHexSchema2.optional(),
   width: z2.number().min(0.5).max(10).optional(),
   strokeWidth: z2.number().min(0.5).max(10).default(2),
   arrowSize: z2.number().min(4).max(32).optional(),
   arrowPlacement: z2.enum(["endpoint", "boundary"]).default("endpoint"),
   opacity: z2.number().min(0).max(1).default(1),
-  routing: z2.enum(["auto", "orthogonal", "curve", "arc"]).default("auto"),
+  routing: z2.enum(["auto", "orthogonal", "curve", "arc", "straight"]).default("auto"),
+  curveMode: z2.enum(["normal", "ellipse"]).default("normal"),
   tension: z2.number().min(0.1).max(0.8).default(0.35),
   fromAnchor: anchorHintSchema.optional(),
   toAnchor: anchorHintSchema.optional()
@@ -1137,7 +1157,11 @@ var autoLayoutConfigSchema = z2.object({
   /** Sort strategy for radial layout node ordering. Only relevant when algorithm is 'radial'. */
   radialSortBy: z2.enum(["id", "connections"]).optional(),
   /** Explicit center used by curve/arc connection routing. */
-  diagramCenter: diagramCenterSchema.optional()
+  diagramCenter: diagramCenterSchema.optional(),
+  /** Horizontal radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRx: z2.number().positive().optional(),
+  /** Vertical radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRy: z2.number().positive().optional()
 }).strict();
 var gridLayoutConfigSchema = z2.object({
   mode: z2.literal("grid"),
@@ -1147,7 +1171,11 @@ var gridLayoutConfigSchema = z2.object({
   cardMaxHeight: z2.number().int().min(32).max(4096).optional(),
   equalHeight: z2.boolean().default(false),
   /** Explicit center used by curve/arc connection routing. */
-  diagramCenter: diagramCenterSchema.optional()
+  diagramCenter: diagramCenterSchema.optional(),
+  /** Horizontal radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRx: z2.number().positive().optional(),
+  /** Vertical radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRy: z2.number().positive().optional()
 }).strict();
 var stackLayoutConfigSchema = z2.object({
   mode: z2.literal("stack"),
@@ -1155,7 +1183,11 @@ var stackLayoutConfigSchema = z2.object({
   gap: z2.number().int().min(0).max(256).default(24),
   alignment: z2.enum(["start", "center", "end", "stretch"]).default("stretch"),
   /** Explicit center used by curve/arc connection routing. */
-  diagramCenter: diagramCenterSchema.optional()
+  diagramCenter: diagramCenterSchema.optional(),
+  /** Horizontal radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRx: z2.number().positive().optional(),
+  /** Vertical radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRy: z2.number().positive().optional()
 }).strict();
 var manualPositionSchema = z2.object({
   x: z2.number().int(),
@@ -1167,7 +1199,11 @@ var manualLayoutConfigSchema = z2.object({
   mode: z2.literal("manual"),
   positions: z2.record(z2.string().min(1), manualPositionSchema).default({}),
   /** Explicit center used by curve/arc connection routing. */
-  diagramCenter: diagramCenterSchema.optional()
+  diagramCenter: diagramCenterSchema.optional(),
+  /** Horizontal radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRx: z2.number().positive().optional(),
+  /** Vertical radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRy: z2.number().positive().optional()
 }).strict();
 var layoutConfigSchema = z2.discriminatedUnion("mode", [
   autoLayoutConfigSchema,
@@ -1232,7 +1268,11 @@ var diagramElementSchema = z2.discriminatedUnion("type", [
 var diagramLayoutSchema = z2.object({
   mode: z2.enum(["manual", "auto"]).default("manual"),
   positions: z2.record(z2.string(), diagramPositionSchema).optional(),
-  diagramCenter: diagramCenterSchema.optional()
+  diagramCenter: diagramCenterSchema.optional(),
+  /** Horizontal radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRx: z2.number().positive().optional(),
+  /** Vertical radius for shared ellipse used by curveMode: 'ellipse'. */
+  ellipseRy: z2.number().positive().optional()
 }).strict();
 var diagramSpecSchema = z2.object({
   version: z2.literal(1),
@@ -2760,12 +2800,12 @@ var MACOS_DOTS = [
   { fill: "#27C93F", stroke: "#1AAB29" }
 ];
 function drawMacosDots(ctx, x, y) {
-  for (const [index, dot2] of MACOS_DOTS.entries()) {
+  for (const [index, dot] of MACOS_DOTS.entries()) {
     ctx.beginPath();
     ctx.arc(x + index * DOT_SPACING, y, DOT_RADIUS, 0, Math.PI * 2);
     ctx.closePath();
-    ctx.fillStyle = dot2.fill;
-    ctx.strokeStyle = dot2.stroke;
+    ctx.fillStyle = dot.fill;
+    ctx.strokeStyle = dot.stroke;
     ctx.lineWidth = DOT_STROKE_WIDTH;
     ctx.fill();
     ctx.stroke();
@@ -3170,16 +3210,6 @@ function drawBezier(ctx, points, style) {
   ctx.quadraticCurveTo(penultimate.x, penultimate.y, last.x, last.y);
   ctx.stroke();
 }
-function drawOrthogonalPath(ctx, from, to, style) {
-  const midX = (from.x + to.x) / 2;
-  applyLineStyle(ctx, style);
-  ctx.beginPath();
-  ctx.moveTo(from.x, from.y);
-  ctx.lineTo(midX, from.y);
-  ctx.lineTo(midX, to.y);
-  ctx.lineTo(to.x, to.y);
-  ctx.stroke();
-}
 
 // src/renderers/connection.ts
 var ELLIPSE_KAPPA = 4 * (Math.sqrt(2) - 1) / 3;
@@ -3262,56 +3292,71 @@ function curveRoute(fromBounds, toBounds, diagramCenter, tension, fromAnchor, to
   const cp2 = { x: p3.x + n3.x * offset, y: p3.y + n3.y * offset };
   return [p0, cp1, cp2, p3];
 }
-function dot(a, b) {
-  return a.x * b.x + a.y * b.y;
-}
-function localToWorld(origin, axisX, axisY, local) {
-  return {
-    x: origin.x + axisX.x * local.x + axisY.x * local.y,
-    y: origin.y + axisX.y * local.x + axisY.y * local.y
-  };
+function inferEllipseParams(nodeBounds, explicitCenter, explicitRx, explicitRy) {
+  if (nodeBounds.length === 0) {
+    return {
+      cx: explicitCenter?.x ?? 0,
+      cy: explicitCenter?.y ?? 0,
+      rx: explicitRx ?? 1,
+      ry: explicitRy ?? 1
+    };
+  }
+  const centers = nodeBounds.map(rectCenter);
+  const cx = explicitCenter?.x ?? centers.reduce((sum, c) => sum + c.x, 0) / centers.length;
+  const cy = explicitCenter?.y ?? centers.reduce((sum, c) => sum + c.y, 0) / centers.length;
+  const rx = explicitRx ?? Math.max(1, ...centers.map((c) => Math.abs(c.x - cx)));
+  const ry = explicitRy ?? Math.max(1, ...centers.map((c) => Math.abs(c.y - cy)));
+  return { cx, cy, rx, ry };
 }
-function arcRoute(fromBounds, toBounds, diagramCenter, tension, fromAnchor, toAnchor) {
+function ellipseRoute(fromBounds, toBounds, ellipse, fromAnchor, toAnchor) {
   const fromCenter = rectCenter(fromBounds);
   const toCenter = rectCenter(toBounds);
-  const start = resolveAnchor(fromBounds, fromAnchor, toCenter);
-  const end = resolveAnchor(toBounds, toAnchor, fromCenter);
-  const chord = { x: end.x - start.x, y: end.y - start.y };
-  const chordLength = Math.hypot(chord.x, chord.y);
-  if (chordLength < 1e-6) {
-    const mid = { x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 };
-    return [
-      [start, start, mid, mid],
-      [mid, mid, end, end]
-    ];
-  }
-  const axisX = { x: chord.x / chordLength, y: chord.y / chordLength };
-  let axisY = { x: -axisX.y, y: axisX.x };
-  const midpoint = { x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 };
-  const outwardHint = outwardNormal(midpoint, diagramCenter);
-  if (dot(axisY, outwardHint) < 0) {
-    axisY = { x: -axisY.x, y: -axisY.y };
-  }
-  const semiMajor = chordLength / 2;
-  const semiMinor = Math.max(12, chordLength * tension * 0.75);
-  const p0Local = { x: -semiMajor, y: 0 };
-  const cp1Local = { x: -semiMajor, y: ELLIPSE_KAPPA * semiMinor };
-  const cp2Local = { x: -ELLIPSE_KAPPA * semiMajor, y: semiMinor };
-  const pMidLocal = { x: 0, y: semiMinor };
-  const cp3Local = { x: ELLIPSE_KAPPA * semiMajor, y: semiMinor };
-  const cp4Local = { x: semiMajor, y: ELLIPSE_KAPPA * semiMinor };
-  const p3Local = { x: semiMajor, y: 0 };
-  const p0 = localToWorld(midpoint, axisX, axisY, p0Local);
-  const cp1 = localToWorld(midpoint, axisX, axisY, cp1Local);
-  const cp2 = localToWorld(midpoint, axisX, axisY, cp2Local);
-  const pMid = localToWorld(midpoint, axisX, axisY, pMidLocal);
-  const cp3 = localToWorld(midpoint, axisX, axisY, cp3Local);
-  const cp4 = localToWorld(midpoint, axisX, axisY, cp4Local);
-  const p3 = localToWorld(midpoint, axisX, axisY, p3Local);
-  return [
-    [p0, cp1, cp2, pMid],
-    [pMid, cp3, cp4, p3]
-  ];
+  const p0 = resolveAnchor(fromBounds, fromAnchor, toCenter);
+  const p3 = resolveAnchor(toBounds, toAnchor, fromCenter);
+  const theta1 = Math.atan2(
+    (fromCenter.y - ellipse.cy) / ellipse.ry,
+    (fromCenter.x - ellipse.cx) / ellipse.rx
+  );
+  const theta2 = Math.atan2(
+    (toCenter.y - ellipse.cy) / ellipse.ry,
+    (toCenter.x - ellipse.cx) / ellipse.rx
+  );
+  let angularSpan = theta2 - theta1;
+  while (angularSpan > Math.PI) angularSpan -= 2 * Math.PI;
+  while (angularSpan <= -Math.PI) angularSpan += 2 * Math.PI;
+  const absSpan = Math.abs(angularSpan);
+  const kappa = absSpan < 1e-6 ? 0 : 4 / 3 * Math.tan(absSpan / 4);
+  const tangent1 = {
+    x: -ellipse.rx * Math.sin(theta1),
+    y: ellipse.ry * Math.cos(theta1)
+  };
+  const tangent2 = {
+    x: -ellipse.rx * Math.sin(theta2),
+    y: ellipse.ry * Math.cos(theta2)
+  };
+  const len1 = Math.hypot(tangent1.x, tangent1.y) || 1;
+  const len2 = Math.hypot(tangent2.x, tangent2.y) || 1;
+  const norm1 = { x: tangent1.x / len1, y: tangent1.y / len1 };
+  const norm2 = { x: tangent2.x / len2, y: tangent2.y / len2 };
+  const chordLength = Math.hypot(p3.x - p0.x, p3.y - p0.y);
+  const cpDistance = chordLength * kappa * 0.5;
+  const sign = angularSpan >= 0 ? 1 : -1;
+  const cp1 = {
+    x: p0.x + norm1.x * cpDistance * sign,
+    y: p0.y + norm1.y * cpDistance * sign
+  };
+  const cp2 = {
+    x: p3.x - norm2.x * cpDistance * sign,
+    y: p3.y - norm2.y * cpDistance * sign
+  };
+  return [p0, cp1, cp2, p3];
+}
+function straightRoute(fromBounds, toBounds, fromAnchor, toAnchor) {
+  const fromC = rectCenter(fromBounds);
+  const toC = rectCenter(toBounds);
+  const p0 = resolveAnchor(fromBounds, fromAnchor, toC);
+  const p3 = resolveAnchor(toBounds, toAnchor, fromC);
+  return [p0, p3];
 }
 function orthogonalRoute(fromBounds, toBounds, fromAnchor, toAnchor) {
   const fromC = rectCenter(fromBounds);
@@ -3357,15 +3402,6 @@ function findBoundaryIntersection(p0, cp1, cp2, p3, targetRect, searchFromEnd) {
   }
   return void 0;
 }
-function pointAlongArc(route, t) {
-  const [first, second] = route;
-  if (t <= 0.5) {
-    const localT2 = Math.max(0, Math.min(1, t * 2));
-    return bezierPointAt(first[0], first[1], first[2], first[3], localT2);
-  }
-  const localT = Math.max(0, Math.min(1, (t - 0.5) * 2));
-  return bezierPointAt(second[0], second[1], second[2], second[3], localT);
-}
 function computeDiagramCenter(nodeBounds, canvasCenter) {
   if (nodeBounds.length === 0) {
     return canvasCenter ?? { x: 0, y: 0 };
@@ -3419,11 +3455,36 @@ function pointAlongPolyline(points, t) {
   }
   return points[points.length - 1];
 }
-function drawCubicInterpolatedPath(ctx, points, style) {
+function createConnectionGradient(ctx, start, end, fromColor, baseColor, toColor) {
+  const gradient = ctx.createLinearGradient(start.x, start.y, end.x, end.y);
+  gradient.addColorStop(0, fromColor);
+  gradient.addColorStop(0.5, baseColor);
+  gradient.addColorStop(1, toColor);
+  return gradient;
+}
+function resolveConnectionStroke(ctx, start, end, fromColor, baseColor, toColor) {
+  if (!fromColor || !toColor) {
+    return baseColor;
+  }
+  return createConnectionGradient(ctx, start, end, fromColor, baseColor, toColor);
+}
+function drawOrthogonalPathWithStroke(ctx, from, to, style, stroke) {
+  const midX = (from.x + to.x) / 2;
+  ctx.strokeStyle = stroke;
+  ctx.lineWidth = style.width;
+  ctx.setLineDash(style.dash ?? []);
+  ctx.beginPath();
+  ctx.moveTo(from.x, from.y);
+  ctx.lineTo(midX, from.y);
+  ctx.lineTo(midX, to.y);
+  ctx.lineTo(to.x, to.y);
+  ctx.stroke();
+}
+function drawCubicInterpolatedPath(ctx, points, style, stroke) {
   if (points.length < 2) {
     return;
   }
-  ctx.strokeStyle = style.color;
+  ctx.strokeStyle = stroke;
   ctx.lineWidth = style.width;
   ctx.setLineDash(style.dash ?? []);
   ctx.beginPath();
@@ -3463,8 +3524,19 @@ function polylineBounds(points) {
   };
 }
 function renderConnection(ctx, conn, fromBounds, toBounds, theme, edgeRoute, options) {
-  const routing = conn.routing ?? "auto";
-  const strokeStyle = conn.strokeStyle ?? conn.style ?? "solid";
+  let routing = conn.routing ?? "auto";
+  let curveMode = conn.curveMode ?? "normal";
+  if (conn.strokeStyle !== void 0) {
+    console.warn("connection.strokeStyle is deprecated, use style instead");
+  }
+  if (routing === "arc") {
+    console.warn(
+      "connection routing: 'arc' is deprecated. Use routing: 'curve' with curveMode: 'ellipse' instead."
+    );
+    routing = "curve";
+    curveMode = "ellipse";
+  }
+  const strokeStyle = conn.style ?? conn.strokeStyle ?? "solid";
   const strokeWidth = conn.width ?? conn.strokeWidth ?? 2;
   const tension = conn.tension ?? 0.35;
   const dash = dashFromStyle(strokeStyle);
@@ -3486,15 +3558,31 @@ function renderConnection(ctx, conn, fromBounds, toBounds, theme, edgeRoute, opt
   ctx.globalAlpha = conn.opacity;
   const arrowPlacement = conn.arrowPlacement ?? "endpoint";
   if (routing === "curve") {
-    const [p0, cp1, cp2, p3] = curveRoute(
-      fromBounds,
-      toBounds,
-      diagramCenter,
-      tension,
-      conn.fromAnchor,
-      conn.toAnchor
-    );
-    ctx.strokeStyle = style.color;
+    let p0;
+    let cp1;
+    let cp2;
+    let p3;
+    if (curveMode === "ellipse") {
+      const ellipse = options?.ellipseParams ?? inferEllipseParams([fromBounds, toBounds]);
+      [p0, cp1, cp2, p3] = ellipseRoute(
+        fromBounds,
+        toBounds,
+        ellipse,
+        conn.fromAnchor,
+        conn.toAnchor
+      );
+    } else {
+      [p0, cp1, cp2, p3] = curveRoute(
+        fromBounds,
+        toBounds,
+        diagramCenter,
+        tension,
+        conn.fromAnchor,
+        conn.toAnchor
+      );
+    }
+    const stroke = resolveConnectionStroke(ctx, p0, p3, conn.fromColor, style.color, conn.toColor);
+    ctx.strokeStyle = stroke;
     ctx.lineWidth = style.width;
     ctx.setLineDash(style.dash ?? []);
     ctx.beginPath();
@@ -3525,50 +3613,22 @@ function renderConnection(ctx, conn, fromBounds, toBounds, theme, edgeRoute, opt
         }
       }
     }
-  } else if (routing === "arc") {
-    const [first, second] = arcRoute(
-      fromBounds,
-      toBounds,
-      diagramCenter,
-      tension,
-      conn.fromAnchor,
-      conn.toAnchor
-    );
-    const [p0, cp1, cp2, pMid] = first;
-    const [, cp3, cp4, p3] = second;
-    ctx.strokeStyle = style.color;
+  } else if (routing === "straight") {
+    const [p0, p3] = straightRoute(fromBounds, toBounds, conn.fromAnchor, conn.toAnchor);
+    const stroke = resolveConnectionStroke(ctx, p0, p3, conn.fromColor, style.color, conn.toColor);
+    ctx.strokeStyle = stroke;
     ctx.lineWidth = style.width;
     ctx.setLineDash(style.dash ?? []);
     ctx.beginPath();
     ctx.moveTo(p0.x, p0.y);
-    ctx.bezierCurveTo(cp1.x, cp1.y, cp2.x, cp2.y, pMid.x, pMid.y);
-    ctx.bezierCurveTo(cp3.x, cp3.y, cp4.x, cp4.y, p3.x, p3.y);
+    ctx.lineTo(p3.x, p3.y);
     ctx.stroke();
-    linePoints = [p0, cp1, cp2, pMid, cp3, cp4, p3];
+    linePoints = [p0, p3];
     startPoint = p0;
     endPoint = p3;
-    startAngle = Math.atan2(p0.y - cp1.y, p0.x - cp1.x);
-    endAngle = Math.atan2(p3.y - cp4.y, p3.x - cp4.x);
-    labelPoint = pointAlongArc([first, second], labelT);
-    if (arrowPlacement === "boundary") {
-      if (conn.arrow === "end" || conn.arrow === "both") {
-        const [, s_cp3, s_cp4, s_p3] = second;
-        const tEnd = findBoundaryIntersection(pMid, s_cp3, s_cp4, s_p3, toBounds, true);
-        if (tEnd !== void 0) {
-          endPoint = bezierPointAt(pMid, s_cp3, s_cp4, s_p3, tEnd);
-          const tangent = bezierTangentAt(pMid, s_cp3, s_cp4, s_p3, tEnd);
-          endAngle = Math.atan2(tangent.y, tangent.x);
-        }
-      }
-      if (conn.arrow === "start" || conn.arrow === "both") {
-        const tStart = findBoundaryIntersection(p0, cp1, cp2, pMid, fromBounds, false);
-        if (tStart !== void 0) {
-          startPoint = bezierPointAt(p0, cp1, cp2, pMid, tStart);
-          const tangent = bezierTangentAt(p0, cp1, cp2, pMid, tStart);
-          startAngle = Math.atan2(tangent.y, tangent.x) + Math.PI;
-        }
-      }
-    }
+    startAngle = Math.atan2(p0.y - p3.y, p0.x - p3.x);
+    endAngle = Math.atan2(p3.y - p0.y, p3.x - p0.x);
+    labelPoint = pointAlongPolyline(linePoints, labelT);
   } else {
     const hasAnchorHints = conn.fromAnchor !== void 0 || conn.toAnchor !== void 0;
     const useElkRoute = routing === "auto" && !hasAnchorHints && (edgeRoute?.points.length ?? 0) >= 2;
@@ -3579,10 +3639,18 @@ function renderConnection(ctx, conn, fromBounds, toBounds, theme, edgeRoute, opt
     endPoint = linePoints[linePoints.length - 1] ?? linePoints[0];
     startAngle = Math.atan2(startSegment.y - linePoints[0].y, startSegment.x - linePoints[0].x) + Math.PI;
     endAngle = Math.atan2(endPoint.y - endStart.y, endPoint.x - endStart.x);
+    const stroke = resolveConnectionStroke(
+      ctx,
+      startPoint,
+      endPoint,
+      conn.fromColor,
+      style.color,
+      conn.toColor
+    );
     if (useElkRoute) {
-      drawCubicInterpolatedPath(ctx, linePoints, style);
+      drawCubicInterpolatedPath(ctx, linePoints, style, stroke);
     } else {
-      drawOrthogonalPath(ctx, startPoint, endPoint, style);
+      drawOrthogonalPathWithStroke(ctx, startPoint, endPoint, style, stroke);
     }
     labelPoint = pointAlongPolyline(linePoints, labelT);
   }
@@ -3887,6 +3955,9 @@ function measureTextBounds(ctx, options) {
 function angleBetween(from, to) {
   return Math.atan2(to.y - from.y, to.x - from.x);
 }
+function degreesToRadians(angle) {
+  return angle * Math.PI / 180;
+}
 function pathBounds(operations) {
   let minX = Number.POSITIVE_INFINITY;
   let minY = Number.POSITIVE_INFINITY;
@@ -4124,6 +4195,34 @@ function renderDrawCommands(ctx, commands, theme) {
         });
         break;
       }
+      case "arc": {
+        const startAngle = degreesToRadians(command.startAngle);
+        const endAngle = degreesToRadians(command.endAngle);
+        withOpacity(ctx, command.opacity, () => {
+          applyDrawShadow(ctx, command.shadow);
+          ctx.beginPath();
+          ctx.setLineDash(command.dash ?? []);
+          ctx.lineWidth = command.width;
+          ctx.strokeStyle = command.color;
+          ctx.arc(command.center.x, command.center.y, command.radius, startAngle, endAngle);
+          ctx.stroke();
+        });
+        rendered.push({
+          id,
+          kind: "draw",
+          bounds: expandRect(
+            {
+              x: command.center.x - command.radius,
+              y: command.center.y - command.radius,
+              width: command.radius * 2,
+              height: command.radius * 2
+            },
+            command.width / 2
+          ),
+          foregroundColor: command.color
+        });
+        break;
+      }
       case "bezier": {
         const points = command.points;
         withOpacity(ctx, command.opacity, () => {
@@ -4767,6 +4866,18 @@ async function renderDesign(input, options = {}) {
   const specHash = computeSpecHash(spec);
   const generatorVersion = options.generatorVersion ?? DEFAULT_GENERATOR_VERSION;
   const renderedAt = options.renderedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const iteration = options.iteration;
+  if (iteration) {
+    if (!Number.isInteger(iteration.iteration) || iteration.iteration <= 0) {
+      throw new Error("Iteration metadata requires iteration to be a positive integer.");
+    }
+    if (iteration.maxIterations != null && (!Number.isInteger(iteration.maxIterations) || iteration.maxIterations <= 0)) {
+      throw new Error("Iteration metadata requires maxIterations to be a positive integer.");
+    }
+    if (iteration.maxIterations != null && iteration.maxIterations < iteration.iteration) {
+      throw new Error("Iteration metadata requires maxIterations to be >= iteration.");
+    }
+  }
   const renderScale = resolveRenderScale(spec);
   const canvas = createCanvas(spec.canvas.width * renderScale, spec.canvas.height * renderScale);
   const ctx = canvas.getContext("2d");
@@ -4946,10 +5057,19 @@ async function renderDesign(input, options = {}) {
         break;
     }
   }
-  const diagramCenter = spec.layout.diagramCenter ?? computeDiagramCenter(
-    spec.elements.filter((element) => element.type !== "connection").map((element) => elementRects.get(element.id)).filter((rect) => rect != null),
-    { x: spec.canvas.width / 2, y: spec.canvas.height / 2 }
+  const nodeBounds = spec.elements.filter((element) => element.type !== "connection").map((element) => elementRects.get(element.id)).filter((rect) => rect != null);
+  const diagramCenter = spec.layout.diagramCenter ?? computeDiagramCenter(nodeBounds, { x: spec.canvas.width / 2, y: spec.canvas.height / 2 });
+  const layoutEllipseRx = "ellipseRx" in spec.layout ? spec.layout.ellipseRx : void 0;
+  const layoutEllipseRy = "ellipseRy" in spec.layout ? spec.layout.ellipseRy : void 0;
+  const hasEllipseConnections = spec.elements.some(
+    (el) => el.type === "connection" && (el.curveMode === "ellipse" || el.routing === "arc")
   );
+  const ellipseParams = hasEllipseConnections ? inferEllipseParams(
+    nodeBounds,
+    spec.layout.diagramCenter ?? diagramCenter,
+    layoutEllipseRx,
+    layoutEllipseRy
+  ) : void 0;
   for (const element of spec.elements) {
     if (element.type !== "connection") {
       continue;
@@ -4963,7 +5083,15 @@ async function renderDesign(input, options = {}) {
     }
     const edgeRoute = edgeRoutes?.get(`${element.from}-${element.to}`);
     elements.push(
-      ...renderConnection(ctx, element, fromRect, toRect, theme, edgeRoute, { diagramCenter })
+      ...renderConnection(
+        ctx,
+        element,
+        fromRect,
+        toRect,
+        theme,
+        edgeRoute,
+        ellipseParams ? { diagramCenter, ellipseParams } : { diagramCenter }
+      )
     );
   }
   if (footerRect && spec.footer) {
@@ -5007,7 +5135,8 @@ async function renderDesign(input, options = {}) {
     layout: {
       safeFrame,
       elements
-    }
+    },
+    ...iteration ? { iteration } : {}
   };
   return {
     png: pngBuffer,
@@ -5314,6 +5443,12 @@ var renderOutputSchema = z3.object({
   artifactHash: z3.string(),
   specHash: z3.string(),
   layoutMode: z3.string(),
+  iteration: z3.object({
+    current: z3.number().int().positive(),
+    max: z3.number().int().positive(),
+    isLast: z3.boolean(),
+    notes: z3.string().optional()
+  }).optional(),
   qa: z3.object({
     pass: z3.boolean(),
     issueCount: z3.number(),
@@ -5400,8 +5535,30 @@ function readCodeRange(code, start, end) {
   const lines = code.split(/\r?\n/u);
   return lines.slice(start - 1, end).join("\n");
 }
+function parseIterationMeta(options) {
+  if (options.iteration == null) {
+    if (options.maxIterations != null || options.iterationNotes || options.previousHash) {
+      throw new Error(
+        "--iteration is required when using --max-iterations, --iteration-notes, or --previous-hash."
+      );
+    }
+    return void 0;
+  }
+  if (options.maxIterations != null && options.maxIterations < options.iteration) {
+    throw new Error("--max-iterations must be greater than or equal to --iteration.");
+  }
+  return {
+    iteration: options.iteration,
+    ...options.maxIterations != null ? { maxIterations: options.maxIterations } : {},
+    ...options.iterationNotes ? { notes: options.iterationNotes } : {},
+    ...options.previousHash ? { previousHash: options.previousHash } : {}
+  };
+}
 async function runRenderPipeline(spec, options) {
-  const renderResult = await renderDesign(spec, { generatorVersion: pkg.version });
+  const renderResult = await renderDesign(spec, {
+    generatorVersion: pkg.version,
+    ...options.iteration ? { iteration: options.iteration } : {}
+  });
   const written = await writeRenderArtifacts(renderResult, options.out);
   const specPath = options.specOut ? resolve4(options.specOut) : specPathFor(written.metadataPath);
   await mkdir2(dirname3(specPath), { recursive: true });
@@ -5418,6 +5575,14 @@ async function runRenderPipeline(spec, options) {
     artifactHash: written.metadata.artifactHash,
     specHash: written.metadata.specHash,
     layoutMode: spec.layout.mode,
+    ...written.metadata.iteration ? {
+      iteration: {
+        current: written.metadata.iteration.iteration,
+        max: written.metadata.iteration.maxIterations ?? written.metadata.iteration.iteration,
+        isLast: (written.metadata.iteration.maxIterations ?? written.metadata.iteration.iteration) === written.metadata.iteration.iteration,
+        ...written.metadata.iteration.notes ? { notes: written.metadata.iteration.notes } : {}
+      }
+    } : {},
     qa: {
       pass: qa.pass,
       issueCount: qa.issues.length,
@@ -5431,6 +5596,10 @@ cli.command("render", {
     spec: z3.string().describe('Path to DesignSpec JSON file (or "-" to read JSON from stdin)'),
     out: z3.string().describe("Output file path (.png) or output directory"),
     specOut: z3.string().optional().describe("Optional explicit output path for normalized spec JSON"),
+    iteration: z3.number().int().positive().optional().describe("Optional iteration number for iterative workflows (1-indexed)"),
+    iterationNotes: z3.string().optional().describe("Optional notes for the current iteration metadata"),
+    maxIterations: z3.number().int().positive().optional().describe("Optional maximum planned iteration count"),
+    previousHash: z3.string().optional().describe("Optional artifact hash from the previous iteration"),
     allowQaFail: z3.boolean().default(false).describe("Allow render success even if QA fails")
   }),
   output: renderOutputSchema,
@@ -5445,9 +5614,26 @@ cli.command("render", {
   ],
   async run(c) {
     const spec = parseDesignSpec(await readJson(c.options.spec));
+    let iteration;
+    try {
+      iteration = parseIterationMeta({
+        ...c.options.iteration != null ? { iteration: c.options.iteration } : {},
+        ...c.options.maxIterations != null ? { maxIterations: c.options.maxIterations } : {},
+        ...c.options.iterationNotes ? { iterationNotes: c.options.iterationNotes } : {},
+        ...c.options.previousHash ? { previousHash: c.options.previousHash } : {}
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return c.error({
+        code: "INVALID_ITERATION_OPTIONS",
+        message,
+        retryable: false
+      });
+    }
     const runReport = await runRenderPipeline(spec, {
       out: c.options.out,
-      ...c.options.specOut ? { specOut: c.options.specOut } : {}
+      ...c.options.specOut ? { specOut: c.options.specOut } : {},
+      ...iteration ? { iteration } : {}
     });
     if (!runReport.qa.pass && !c.options.allowQaFail) {
       return c.error({