@spectratools/graphic-designer-cli 0.8.0 → 0.10.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,
@@ -1039,6 +1055,8 @@ var connectionElementSchema = z2.object({
   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(),
@@ -1867,6 +1885,38 @@ function renderFlowNode(ctx, node, bounds, theme) {
     ctx.shadowOffsetX = 0;
     ctx.shadowOffsetY = 0;
   }
+  if (node.accentColor) {
+    const barWidth = node.accentBarWidth ?? 3;
+    const effectiveRadius = node.shape === "box" ? 0 : cornerRadius;
+    ctx.save();
+    ctx.beginPath();
+    ctx.roundRect(bounds.x, bounds.y, bounds.width, bounds.height, effectiveRadius);
+    ctx.clip();
+    ctx.fillStyle = node.accentColor;
+    ctx.fillRect(bounds.x, bounds.y, barWidth, bounds.height);
+    ctx.restore();
+  }
+  if (node.glowColor) {
+    const glowW = node.glowWidth ?? 16;
+    const glowOp = node.glowOpacity ?? 0.15;
+    ctx.save();
+    ctx.beginPath();
+    ctx.roundRect(bounds.x, bounds.y, bounds.width, bounds.height, cornerRadius);
+    ctx.clip();
+    const barOffset = node.accentColor ? node.accentBarWidth ?? 3 : 0;
+    const gradient = ctx.createLinearGradient(
+      bounds.x + barOffset,
+      bounds.y,
+      bounds.x + barOffset + glowW,
+      bounds.y
+    );
+    gradient.addColorStop(0, node.glowColor);
+    gradient.addColorStop(1, "rgba(0,0,0,0)");
+    ctx.globalAlpha = glowOp;
+    ctx.fillStyle = gradient;
+    ctx.fillRect(bounds.x, bounds.y, bounds.width, bounds.height);
+    ctx.restore();
+  }
   const headingFont = resolveFont(theme.fonts.heading, "heading");
   const bodyFont = resolveFont(theme.fonts.body, "body");
   const monoFont = resolveFont(theme.fonts.mono, "mono");
@@ -3138,16 +3188,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;
@@ -3387,11 +3427,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();
@@ -3462,7 +3527,8 @@ function renderConnection(ctx, conn, fromBounds, toBounds, theme, edgeRoute, opt
       conn.fromAnchor,
       conn.toAnchor
     );
-    ctx.strokeStyle = style.color;
+    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();
@@ -3504,7 +3570,8 @@ function renderConnection(ctx, conn, fromBounds, toBounds, theme, edgeRoute, opt
     );
     const [p0, cp1, cp2, pMid] = first;
     const [, cp3, cp4, p3] = second;
-    ctx.strokeStyle = style.color;
+    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();
@@ -3547,10 +3614,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);
   }
@@ -3855,6 +3930,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;
@@ -4092,6 +4170,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, () => {
@@ -4248,6 +4354,84 @@ function renderDrawCommands(ctx, commands, theme) {
         });
         break;
       }
+      case "text-row": {
+        const segments = command.segments;
+        if (segments.length === 0) break;
+        const resolveSegment = (seg) => ({
+          text: seg.text,
+          fontSize: seg.fontSize ?? command.defaultFontSize,
+          fontWeight: seg.fontWeight ?? command.defaultFontWeight,
+          fontFamily: resolveDrawFont(theme, seg.fontFamily ?? command.defaultFontFamily),
+          color: seg.color ?? command.defaultColor
+        });
+        const measured = [];
+        let totalWidth = 0;
+        let maxAscent = 0;
+        let maxDescent = 0;
+        for (const seg of segments) {
+          const resolved = resolveSegment(seg);
+          applyFont(ctx, {
+            size: resolved.fontSize,
+            weight: resolved.fontWeight,
+            family: resolved.fontFamily
+          });
+          const metrics = ctx.measureText(resolved.text);
+          const width = metrics.width;
+          const ascent = metrics.actualBoundingBoxAscent || 0;
+          const descent = metrics.actualBoundingBoxDescent || 0;
+          totalWidth += width;
+          maxAscent = Math.max(maxAscent, ascent);
+          maxDescent = Math.max(maxDescent, descent);
+          measured.push({ width, resolved });
+        }
+        let cursorX;
+        if (command.align === "center") {
+          cursorX = command.x - totalWidth / 2;
+        } else if (command.align === "right") {
+          cursorX = command.x - totalWidth;
+        } else {
+          cursorX = command.x;
+        }
+        const startX = cursorX;
+        withOpacity(ctx, command.opacity, () => {
+          ctx.textBaseline = command.baseline;
+          for (const { width, resolved } of measured) {
+            applyFont(ctx, {
+              size: resolved.fontSize,
+              weight: resolved.fontWeight,
+              family: resolved.fontFamily
+            });
+            ctx.fillStyle = resolved.color;
+            ctx.textAlign = "left";
+            ctx.fillText(resolved.text, cursorX, command.y);
+            cursorX += width;
+          }
+        });
+        const height = Math.max(1, maxAscent + maxDescent);
+        let topY;
+        if (command.baseline === "top") {
+          topY = command.y;
+        } else if (command.baseline === "middle") {
+          topY = command.y - height / 2;
+        } else if (command.baseline === "bottom") {
+          topY = command.y - height;
+        } else {
+          topY = command.y - maxAscent;
+        }
+        rendered.push({
+          id,
+          kind: "draw",
+          bounds: {
+            x: startX,
+            y: topY,
+            width: Math.max(1, totalWidth),
+            height
+          },
+          foregroundColor: command.defaultColor,
+          backgroundColor: theme.background
+        });
+        break;
+      }
     }
   }
   return rendered;
@@ -4657,6 +4841,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");
@@ -4897,7 +5093,8 @@ async function renderDesign(input, options = {}) {
     layout: {
       safeFrame,
       elements
-    }
+    },
+    ...iteration ? { iteration } : {}
   };
   return {
     png: pngBuffer,
@@ -5204,6 +5401,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(),
@@ -5290,8 +5493,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 });
@@ -5308,6 +5533,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,
@@ -5321,6 +5554,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,
@@ -5335,9 +5572,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({

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Cli } from 'incur';
-import { T as ThemeInput, D as DesignSpec, a as Rect$1, b as DrawCommand, c as Theme, d as RenderedElement, A as AnchorHint, C as ConnectionElement } from './spec.schema-B_Z-KNqt.js';
-export { e as AutoLayoutConfig, B as BuiltInTheme, f as CardElement, g as CodeBlockElement, h as ConstraintSpec, i as DEFAULT_GENERATOR_VERSION, j as DEFAULT_RAINBOW_COLORS, k as Decorator, l as DesignCardSpec, m as DesignSafeFrame, n as DesignTheme, o as DiagramElement, p as DiagramLayout, q as DiagramSpec, r as DrawBadge, s as DrawBezier, t as DrawCircle, u as DrawFontFamily, v as DrawGradientRect, w as DrawLine, x as DrawPath, y as DrawPoint, z as DrawRect, E as DrawShadow, F as DrawText, G as DrawTextRow, H as DrawTextRowSegment, I as Element, J as FlowNodeElement, K as Gradient, L as GradientOverlayDecorator, M as GradientSpec, N as GradientStop, O as GridLayoutConfig, P as ImageElement, Q as LayoutConfig, S as LayoutSnapshot, U as ManualLayoutConfig, V as RainbowRuleDecorator, R as RenderMetadata, W as RenderResult, X as ShapeElement, Y as StackLayoutConfig, Z as TerminalElement, _ as TextElement, $ as ThemeInput, a0 as VignetteDecorator, a1 as WrittenArtifacts, a2 as builtInThemeBackgrounds, a3 as builtInThemes, a4 as computeSpecHash, a5 as connectionElementSchema, a6 as defaultAutoLayout, a7 as defaultCanvas, a8 as defaultConstraints, a9 as defaultGridLayout, aa as defaultLayout, ab as defaultStackLayout, ac as defaultTheme, ad as deriveSafeFrame, ae as designSpecSchema, af as diagramElementSchema, ag as diagramLayoutSchema, ah as diagramSpecSchema, ai as drawGradientRect, aj as drawRainbowRule, ak as drawVignette, al as flowNodeElementSchema, am as inferLayout, an as inferSidecarPath, ao as parseDesignSpec, ap as parseDiagramSpec, aq as renderDesign, ar as resolveTheme, as as writeRenderArtifacts } from './spec.schema-B_Z-KNqt.js';
+import { T as ThemeInput, D as DesignSpec, a as Rect$1, b as DrawCommand, c as Theme, d as RenderedElement, A as AnchorHint, C as ConnectionElement } from './spec.schema-B6sXTTou.js';
+export { e as AutoLayoutConfig, B as BuiltInTheme, f as CardElement, g as CodeBlockElement, h as ConstraintSpec, i as DEFAULT_GENERATOR_VERSION, j as DEFAULT_RAINBOW_COLORS, k as Decorator, l as DesignCardSpec, m as DesignSafeFrame, n as DesignTheme, o as DiagramElement, p as DiagramLayout, q as DiagramSpec, r as DrawArc, s as DrawBadge, t as DrawBezier, u as DrawCircle, v as DrawFontFamily, w as DrawGradientRect, x as DrawLine, y as DrawPath, z as DrawPoint, E as DrawRect, F as DrawShadow, G as DrawText, H as DrawTextRow, I as DrawTextRowSegment, J as Element, K as FlowNodeElement, L as Gradient, M as GradientOverlayDecorator, N as GradientSpec, O as GradientStop, P as GridLayoutConfig, Q as ImageElement, S as IterationMeta, U as LayoutConfig, V as LayoutSnapshot, W as ManualLayoutConfig, X as RainbowRuleDecorator, Y as RenderDesignOptions, R as RenderMetadata, Z as RenderResult, _ as ShapeElement, $ as StackLayoutConfig, a0 as TerminalElement, a1 as TextElement, a2 as ThemeInput, a3 as VignetteDecorator, a4 as WrittenArtifacts, a5 as builtInThemeBackgrounds, a6 as builtInThemes, a7 as computeSpecHash, a8 as connectionElementSchema, a9 as defaultAutoLayout, aa as defaultCanvas, ab as defaultConstraints, ac as defaultGridLayout, ad as defaultLayout, ae as defaultStackLayout, af as defaultTheme, ag as deriveSafeFrame, ah as designSpecSchema, ai as diagramElementSchema, aj as diagramLayoutSchema, ak as diagramSpecSchema, al as drawGradientRect, am as drawRainbowRule, an as drawVignette, ao as flowNodeElementSchema, ap as inferLayout, aq as inferSidecarPath, ar as parseDesignSpec, as as parseDiagramSpec, at as renderDesign, au as resolveTheme, av as writeRenderArtifacts } from './spec.schema-B6sXTTou.js';
 import { SKRSContext2D } from '@napi-rs/canvas';
 export { QaIssue, QaReferenceResult, QaReport, QaSeverity, readMetadata, runQa } from './qa.js';
 import { Highlighter } from 'shiki';
@@ -223,10 +223,10 @@ type ElkLayoutResult = LayoutResult & {
 /**
  * Render an array of freestyle draw commands onto a canvas context.
  *
- * Supports eight command types: `rect`, `circle`, `text`, `line`, `bezier`,
- * `path`, `badge`, and `gradient-rect`. Each command is rendered in order and
- * produces a corresponding {@link RenderedElement} with computed bounds for
- * downstream QA checks.
+ * Supports draw command types including `rect`, `circle`, `text`, `line`,
+ * `arc`, `bezier`, `path`, `badge`, `gradient-rect`, `grid`, and `text-row`.
+ * Each command is rendered in order and produces a corresponding
+ * {@link RenderedElement} with computed bounds for downstream QA checks.
  *
  * @param ctx - The `@napi-rs/canvas` 2D rendering context to draw into.
  * @param commands - Array of {@link DrawCommand} objects from the design spec's