@spectratools/graphic-designer-cli 0.9.0 → 0.11.0

package/dist/index.js

@@ -829,6 +829,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()
@@ -913,6 +928,7 @@ var drawCommandSchema = z2.discriminatedUnion("type", [
   drawCircleSchema,
   drawTextSchema,
   drawLineSchema,
+  drawArcSchema,
   drawBezierSchema,
   drawPathSchema,
   drawBadgeSchema,
@@ -1044,17 +1060,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()
@@ -1147,7 +1167,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"),
@@ -1157,7 +1181,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"),
@@ -1165,7 +1193,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(),
@@ -1177,7 +1209,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,
@@ -1242,7 +1278,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),
@@ -3187,16 +3227,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;
@@ -3330,6 +3360,72 @@ function arcRoute(fromBounds, toBounds, diagramCenter, tension, fromAnchor, toAn
     [pMid, cp3, cp4, p3]
   ];
 }
+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 ellipseRoute(fromBounds, toBounds, ellipse, fromAnchor, toAnchor) {
+  const fromCenter = rectCenter(fromBounds);
+  const toCenter = rectCenter(toBounds);
+  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);
   const toC = rectCenter(toBounds);
@@ -3374,15 +3470,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 };
@@ -3436,11 +3523,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();
@@ -3480,8 +3592,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);
@@ -3503,15 +3626,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();
@@ -3542,50 +3681,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;
@@ -3596,10 +3707,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);
   }
@@ -3904,6 +4023,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;
@@ -4141,6 +4263,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, () => {
@@ -4784,6 +4934,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");
@@ -4963,10 +5125,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;
@@ -4980,7 +5151,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) {
@@ -5024,7 +5203,8 @@ async function renderDesign(input, options = {}) {
     layout: {
       safeFrame,
       elements
-    }
+    },
+    ...iteration ? { iteration } : {}
   };
   return {
     png: pngBuffer,
@@ -5331,6 +5511,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(),
@@ -5417,8 +5603,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 });
@@ -5435,6 +5643,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,
@@ -5448,6 +5664,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,
@@ -5462,9 +5682,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({
@@ -5984,8 +6221,10 @@ export {
   drawRainbowRule,
   drawVignette,
   edgeAnchor,
+  ellipseRoute,
   flowNodeElementSchema,
   highlightCode,
+  inferEllipseParams,
   inferLayout,
   inferSidecarPath,
   initHighlighter,
@@ -6004,6 +6243,7 @@ export {
   resolveShikiTheme,
   resolveTheme,
   runQa,
+  straightRoute,
   themeToShikiMap,
   writeRenderArtifacts
 };

package/dist/qa.d.ts

@@ -1,4 +1,4 @@
-import { R as RenderMetadata, D as DesignSpec } from './spec.schema-B_Z-KNqt.js';
+import { R as RenderMetadata, D as DesignSpec } from './spec.schema-CYlOLxmK.js';
 import 'zod';
 import '@napi-rs/canvas';