@spectratools/graphic-designer-cli 0.3.1

package/dist/qa.js

@@ -0,0 +1,901 @@
+// src/qa.ts
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import sharp from "sharp";
+
+// src/code-style.ts
+var CARBON_SURROUND_COLOR = "rgba(171, 184, 195, 1)";
+var DEFAULT_STYLE = {
+  paddingVertical: 56,
+  paddingHorizontal: 56,
+  windowControls: "macos",
+  dropShadow: true,
+  dropShadowOffsetY: 20,
+  dropShadowBlurRadius: 68,
+  surroundColor: CARBON_SURROUND_COLOR,
+  fontSize: 14,
+  lineHeightPercent: 143,
+  scale: 2
+};
+function normalizeScale(scale) {
+  if (scale === 1 || scale === 2 || scale === 4) {
+    return scale;
+  }
+  return DEFAULT_STYLE.scale;
+}
+function resolveCodeBlockStyle(style) {
+  return {
+    paddingVertical: style?.paddingVertical ?? DEFAULT_STYLE.paddingVertical,
+    paddingHorizontal: style?.paddingHorizontal ?? DEFAULT_STYLE.paddingHorizontal,
+    windowControls: style?.windowControls ?? DEFAULT_STYLE.windowControls,
+    dropShadow: style?.dropShadow ?? DEFAULT_STYLE.dropShadow,
+    dropShadowOffsetY: style?.dropShadowOffsetY ?? DEFAULT_STYLE.dropShadowOffsetY,
+    dropShadowBlurRadius: style?.dropShadowBlurRadius ?? DEFAULT_STYLE.dropShadowBlurRadius,
+    surroundColor: style?.surroundColor ?? DEFAULT_STYLE.surroundColor,
+    fontSize: style?.fontSize ?? DEFAULT_STYLE.fontSize,
+    lineHeightPercent: style?.lineHeightPercent ?? DEFAULT_STYLE.lineHeightPercent,
+    scale: normalizeScale(style?.scale)
+  };
+}
+function resolveElementScale(element) {
+  if (element.type !== "code-block" && element.type !== "terminal") {
+    return null;
+  }
+  return resolveCodeBlockStyle(element.style).scale;
+}
+function resolveRenderScale(spec) {
+  let scale = 1;
+  for (const element of spec.elements) {
+    const elementScale = resolveElementScale(element);
+    if (elementScale === null) {
+      continue;
+    }
+    if (elementScale > scale) {
+      scale = elementScale;
+    }
+  }
+  return scale;
+}
+
+// src/spec.schema.ts
+import { z as z2 } from "zod";
+
+// src/themes/builtin.ts
+import { z } from "zod";
+var colorHexSchema = z.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "Expected #RRGGBB or #RRGGBBAA color");
+var fontFamilySchema = z.string().min(1).max(120);
+var codeThemeSchema = z.object({
+  background: colorHexSchema,
+  text: colorHexSchema,
+  comment: colorHexSchema,
+  keyword: colorHexSchema,
+  string: colorHexSchema,
+  number: colorHexSchema,
+  function: colorHexSchema,
+  variable: colorHexSchema,
+  operator: colorHexSchema,
+  punctuation: colorHexSchema
+}).strict();
+var themeSchema = z.object({
+  background: colorHexSchema,
+  surface: colorHexSchema,
+  surfaceMuted: colorHexSchema,
+  surfaceElevated: colorHexSchema,
+  text: colorHexSchema,
+  textMuted: colorHexSchema,
+  textInverse: colorHexSchema,
+  primary: colorHexSchema,
+  secondary: colorHexSchema,
+  accent: colorHexSchema,
+  success: colorHexSchema,
+  warning: colorHexSchema,
+  error: colorHexSchema,
+  info: colorHexSchema,
+  border: colorHexSchema,
+  borderMuted: colorHexSchema,
+  code: codeThemeSchema,
+  fonts: z.object({
+    heading: fontFamilySchema,
+    body: fontFamilySchema,
+    mono: fontFamilySchema
+  }).strict()
+}).strict();
+var builtInThemeSchema = z.enum([
+  "dark",
+  "light",
+  "dracula",
+  "github-dark",
+  "one-dark",
+  "nord"
+]);
+var baseDarkTheme = {
+  background: "#0B1020",
+  surface: "#111936",
+  surfaceMuted: "#1A2547",
+  surfaceElevated: "#202D55",
+  text: "#E8EEFF",
+  textMuted: "#AAB9E8",
+  textInverse: "#0B1020",
+  primary: "#7AA2FF",
+  secondary: "#65E4A3",
+  accent: "#65E4A3",
+  success: "#2FCB7E",
+  warning: "#F4B860",
+  error: "#F97070",
+  info: "#60A5FA",
+  border: "#32426E",
+  borderMuted: "#24345F",
+  code: {
+    background: "#0F172A",
+    text: "#E2E8F0",
+    comment: "#64748B",
+    keyword: "#C084FC",
+    string: "#86EFAC",
+    number: "#FCA5A5",
+    function: "#93C5FD",
+    variable: "#E2E8F0",
+    operator: "#F8FAFC",
+    punctuation: "#CBD5E1"
+  },
+  fonts: {
+    heading: "Space Grotesk",
+    body: "Inter",
+    mono: "JetBrains Mono"
+  }
+};
+var builtInThemes = {
+  dark: baseDarkTheme,
+  light: {
+    ...baseDarkTheme,
+    background: "#F8FAFC",
+    surface: "#FFFFFF",
+    surfaceMuted: "#EEF2FF",
+    surfaceElevated: "#FFFFFF",
+    text: "#0F172A",
+    textMuted: "#334155",
+    textInverse: "#F8FAFC",
+    border: "#CBD5E1",
+    borderMuted: "#E2E8F0",
+    code: {
+      ...baseDarkTheme.code,
+      background: "#F1F5F9",
+      text: "#0F172A",
+      variable: "#1E293B",
+      punctuation: "#334155",
+      operator: "#0F172A"
+    }
+  },
+  dracula: {
+    ...baseDarkTheme,
+    background: "#282A36",
+    surface: "#303247",
+    surfaceMuted: "#3A3D55",
+    surfaceElevated: "#44475A",
+    text: "#F8F8F2",
+    textMuted: "#BD93F9",
+    primary: "#8BE9FD",
+    accent: "#50FA7B",
+    secondary: "#FFB86C",
+    success: "#50FA7B",
+    warning: "#FFB86C",
+    error: "#FF5555",
+    info: "#8BE9FD",
+    border: "#44475A",
+    borderMuted: "#3A3D55"
+  },
+  "github-dark": {
+    ...baseDarkTheme,
+    background: "#0D1117",
+    surface: "#161B22",
+    surfaceMuted: "#1F2632",
+    surfaceElevated: "#21262D",
+    text: "#E6EDF3",
+    textMuted: "#8B949E",
+    primary: "#58A6FF",
+    accent: "#3FB950",
+    secondary: "#A5D6FF",
+    border: "#30363D",
+    borderMuted: "#21262D"
+  },
+  "one-dark": {
+    ...baseDarkTheme,
+    background: "#282C34",
+    surface: "#2F343F",
+    surfaceMuted: "#3A404C",
+    surfaceElevated: "#434A59",
+    text: "#ABB2BF",
+    textMuted: "#7F848E",
+    primary: "#61AFEF",
+    accent: "#98C379",
+    secondary: "#E5C07B",
+    warning: "#E5C07B",
+    error: "#E06C75",
+    border: "#4B5263",
+    borderMuted: "#3A404C"
+  },
+  nord: {
+    ...baseDarkTheme,
+    background: "#2E3440",
+    surface: "#3B4252",
+    surfaceMuted: "#434C5E",
+    surfaceElevated: "#4C566A",
+    text: "#ECEFF4",
+    textMuted: "#D8DEE9",
+    primary: "#88C0D0",
+    accent: "#A3BE8C",
+    secondary: "#81A1C1",
+    success: "#A3BE8C",
+    warning: "#EBCB8B",
+    error: "#BF616A",
+    info: "#5E81AC",
+    border: "#4C566A",
+    borderMuted: "#434C5E"
+  }
+};
+var defaultTheme = builtInThemes.dark;
+
+// src/spec.schema.ts
+var colorHexSchema2 = z2.string().regex(/^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "Expected #RRGGBB or #RRGGBBAA color");
+var gradientStopSchema = z2.object({
+  offset: z2.number().min(0).max(1),
+  color: colorHexSchema2
+}).strict();
+var linearGradientSchema = z2.object({
+  type: z2.literal("linear"),
+  angle: z2.number().default(180),
+  stops: z2.array(gradientStopSchema).min(2)
+}).strict();
+var radialGradientSchema = z2.object({
+  type: z2.literal("radial"),
+  stops: z2.array(gradientStopSchema).min(2)
+}).strict();
+var gradientSchema = z2.discriminatedUnion("type", [linearGradientSchema, radialGradientSchema]);
+var drawFontFamilySchema = z2.enum(["heading", "body", "mono"]);
+var drawRectSchema = z2.object({
+  type: z2.literal("rect"),
+  x: z2.number(),
+  y: z2.number(),
+  width: z2.number().positive(),
+  height: z2.number().positive(),
+  fill: colorHexSchema2.optional(),
+  stroke: colorHexSchema2.optional(),
+  strokeWidth: z2.number().min(0).max(32).default(0),
+  radius: z2.number().min(0).max(256).default(0),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var drawCircleSchema = z2.object({
+  type: z2.literal("circle"),
+  cx: z2.number(),
+  cy: z2.number(),
+  radius: z2.number().positive(),
+  fill: colorHexSchema2.optional(),
+  stroke: colorHexSchema2.optional(),
+  strokeWidth: z2.number().min(0).max(32).default(0),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var drawTextSchema = z2.object({
+  type: z2.literal("text"),
+  x: z2.number(),
+  y: z2.number(),
+  text: z2.string().min(1).max(500),
+  fontSize: z2.number().min(6).max(200).default(16),
+  fontWeight: z2.number().int().min(100).max(900).default(400),
+  fontFamily: drawFontFamilySchema.default("body"),
+  color: colorHexSchema2.default("#FFFFFF"),
+  align: z2.enum(["left", "center", "right"]).default("left"),
+  baseline: z2.enum(["top", "middle", "alphabetic", "bottom"]).default("alphabetic"),
+  letterSpacing: z2.number().min(-10).max(50).default(0),
+  maxWidth: z2.number().positive().optional(),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var drawLineSchema = z2.object({
+  type: z2.literal("line"),
+  x1: z2.number(),
+  y1: z2.number(),
+  x2: z2.number(),
+  y2: z2.number(),
+  color: colorHexSchema2.default("#FFFFFF"),
+  width: z2.number().min(0.5).max(32).default(2),
+  dash: z2.array(z2.number()).max(6).optional(),
+  arrow: z2.enum(["none", "end", "start", "both"]).default("none"),
+  arrowSize: z2.number().min(4).max(32).default(10),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var drawPointSchema = z2.object({
+  x: z2.number(),
+  y: z2.number()
+}).strict();
+var drawBezierSchema = z2.object({
+  type: z2.literal("bezier"),
+  points: z2.array(drawPointSchema).min(2).max(20),
+  color: colorHexSchema2.default("#FFFFFF"),
+  width: z2.number().min(0.5).max(32).default(2),
+  dash: z2.array(z2.number()).max(6).optional(),
+  arrow: z2.enum(["none", "end", "start", "both"]).default("none"),
+  arrowSize: z2.number().min(4).max(32).default(10),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var drawPathSchema = z2.object({
+  type: z2.literal("path"),
+  d: z2.string().min(1).max(4e3),
+  fill: colorHexSchema2.optional(),
+  stroke: colorHexSchema2.optional(),
+  strokeWidth: z2.number().min(0).max(32).default(0),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var drawBadgeSchema = z2.object({
+  type: z2.literal("badge"),
+  x: z2.number(),
+  y: z2.number(),
+  text: z2.string().min(1).max(64),
+  fontSize: z2.number().min(6).max(48).default(12),
+  fontFamily: drawFontFamilySchema.default("mono"),
+  color: colorHexSchema2.default("#FFFFFF"),
+  background: colorHexSchema2.default("#334B83"),
+  paddingX: z2.number().min(0).max(64).default(10),
+  paddingY: z2.number().min(0).max(32).default(4),
+  borderRadius: z2.number().min(0).max(64).default(12),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var drawGradientRectSchema = z2.object({
+  type: z2.literal("gradient-rect"),
+  x: z2.number(),
+  y: z2.number(),
+  width: z2.number().positive(),
+  height: z2.number().positive(),
+  gradient: gradientSchema,
+  radius: z2.number().min(0).max(256).default(0),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var drawCommandSchema = z2.discriminatedUnion("type", [
+  drawRectSchema,
+  drawCircleSchema,
+  drawTextSchema,
+  drawLineSchema,
+  drawBezierSchema,
+  drawPathSchema,
+  drawBadgeSchema,
+  drawGradientRectSchema
+]);
+var defaultCanvas = {
+  width: 1200,
+  height: 675,
+  padding: 48
+};
+var defaultConstraints = {
+  minContrastRatio: 4.5,
+  minFooterSpacing: 16,
+  checkOverlaps: true,
+  maxTextTruncation: 0.1
+};
+var defaultAutoLayout = {
+  mode: "auto",
+  algorithm: "layered",
+  direction: "TB",
+  nodeSpacing: 80,
+  rankSpacing: 120,
+  edgeRouting: "polyline"
+};
+var defaultGridLayout = {
+  mode: "grid",
+  columns: 3,
+  gap: 24,
+  equalHeight: false
+};
+var defaultStackLayout = {
+  mode: "stack",
+  direction: "vertical",
+  gap: 24,
+  alignment: "stretch"
+};
+function inferLayout(elements, explicitLayout) {
+  if (explicitLayout) {
+    return explicitLayout;
+  }
+  const hasFlowNodes = elements.some((element) => element.type === "flow-node");
+  const hasConnections = elements.some((element) => element.type === "connection");
+  const hasOnlyCards = elements.every((element) => element.type === "card");
+  const hasCodeOrTerminal = elements.some(
+    (element) => element.type === "code-block" || element.type === "terminal"
+  );
+  if (hasFlowNodes && hasConnections) {
+    return defaultAutoLayout;
+  }
+  if (hasOnlyCards) {
+    return defaultGridLayout;
+  }
+  if (hasCodeOrTerminal) {
+    return defaultStackLayout;
+  }
+  return defaultGridLayout;
+}
+var cardElementSchema = z2.object({
+  type: z2.literal("card"),
+  id: z2.string().min(1).max(120),
+  title: z2.string().min(1).max(200),
+  body: z2.string().min(1).max(4e3),
+  badge: z2.string().min(1).max(64).optional(),
+  metric: z2.string().min(1).max(80).optional(),
+  tone: z2.enum(["neutral", "accent", "success", "warning", "error"]).default("neutral"),
+  icon: z2.string().min(1).max(64).optional()
+}).strict();
+var flowNodeElementSchema = z2.object({
+  type: z2.literal("flow-node"),
+  id: z2.string().min(1).max(120),
+  shape: z2.enum(["box", "rounded-box", "diamond", "circle", "pill", "cylinder", "parallelogram"]),
+  label: z2.string().min(1).max(200),
+  sublabel: z2.string().min(1).max(300).optional(),
+  sublabelColor: colorHexSchema2.optional(),
+  labelColor: colorHexSchema2.optional(),
+  labelFontSize: z2.number().min(10).max(48).optional(),
+  color: colorHexSchema2.optional(),
+  borderColor: colorHexSchema2.optional(),
+  borderWidth: z2.number().min(0.5).max(8).optional(),
+  cornerRadius: z2.number().min(0).max(64).optional(),
+  width: z2.number().int().min(40).max(800).optional(),
+  height: z2.number().int().min(30).max(600).optional(),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var connectionElementSchema = z2.object({
+  type: z2.literal("connection"),
+  from: z2.string().min(1).max(120),
+  to: z2.string().min(1).max(120),
+  style: z2.enum(["solid", "dashed", "dotted"]).default("solid"),
+  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(),
+  width: z2.number().min(0.5).max(8).optional(),
+  arrowSize: z2.number().min(4).max(32).optional(),
+  opacity: z2.number().min(0).max(1).default(1)
+}).strict();
+var codeBlockStyleSchema = z2.object({
+  paddingVertical: z2.number().min(0).max(128).default(56),
+  paddingHorizontal: z2.number().min(0).max(128).default(56),
+  windowControls: z2.enum(["macos", "bw", "none"]).default("macos"),
+  dropShadow: z2.boolean().default(true),
+  dropShadowOffsetY: z2.number().min(0).max(100).default(20),
+  dropShadowBlurRadius: z2.number().min(0).max(200).default(68),
+  surroundColor: z2.string().optional(),
+  fontSize: z2.number().min(8).max(32).default(14),
+  lineHeightPercent: z2.number().min(100).max(200).default(143),
+  scale: z2.number().int().min(1).max(4).default(2)
+}).partial();
+var codeBlockElementSchema = z2.object({
+  type: z2.literal("code-block"),
+  id: z2.string().min(1).max(120),
+  code: z2.string().min(1),
+  language: z2.string().min(1).max(40),
+  theme: z2.string().min(1).max(80).optional(),
+  showLineNumbers: z2.boolean().default(false),
+  highlightLines: z2.array(z2.number().int().positive()).max(500).optional(),
+  startLine: z2.number().int().positive().default(1),
+  title: z2.string().min(1).max(200).optional(),
+  style: codeBlockStyleSchema.optional()
+}).strict();
+var terminalElementSchema = z2.object({
+  type: z2.literal("terminal"),
+  id: z2.string().min(1).max(120),
+  content: z2.string().min(1),
+  prompt: z2.string().min(1).max(24).optional(),
+  title: z2.string().min(1).max(200).optional(),
+  showPrompt: z2.boolean().default(true),
+  style: codeBlockStyleSchema.optional()
+}).strict();
+var textElementSchema = z2.object({
+  type: z2.literal("text"),
+  id: z2.string().min(1).max(120),
+  content: z2.string().min(1).max(4e3),
+  style: z2.enum(["heading", "subheading", "body", "caption", "code"]),
+  align: z2.enum(["left", "center", "right"]).default("left"),
+  color: colorHexSchema2.optional()
+}).strict();
+var shapeElementSchema = z2.object({
+  type: z2.literal("shape"),
+  id: z2.string().min(1).max(120),
+  shape: z2.enum(["rectangle", "rounded-rectangle", "circle", "ellipse", "line", "arrow"]),
+  fill: colorHexSchema2.optional(),
+  stroke: colorHexSchema2.optional(),
+  strokeWidth: z2.number().min(0).max(64).default(1)
+}).strict();
+var imageElementSchema = z2.object({
+  type: z2.literal("image"),
+  id: z2.string().min(1).max(120),
+  src: z2.string().min(1),
+  alt: z2.string().max(240).optional(),
+  fit: z2.enum(["contain", "cover", "fill", "none"]).default("contain"),
+  borderRadius: z2.number().min(0).default(0)
+}).strict();
+var elementSchema = z2.discriminatedUnion("type", [
+  cardElementSchema,
+  flowNodeElementSchema,
+  connectionElementSchema,
+  codeBlockElementSchema,
+  terminalElementSchema,
+  textElementSchema,
+  shapeElementSchema,
+  imageElementSchema
+]);
+var autoLayoutConfigSchema = z2.object({
+  mode: z2.literal("auto"),
+  algorithm: z2.enum(["layered", "stress", "force", "radial", "box"]).default("layered"),
+  direction: z2.enum(["TB", "BT", "LR", "RL"]).default("TB"),
+  nodeSpacing: z2.number().int().min(0).max(512).default(80),
+  rankSpacing: z2.number().int().min(0).max(512).default(120),
+  edgeRouting: z2.enum(["orthogonal", "polyline", "spline"]).default("polyline"),
+  aspectRatio: z2.number().min(0.5).max(3).optional()
+}).strict();
+var gridLayoutConfigSchema = z2.object({
+  mode: z2.literal("grid"),
+  columns: z2.number().int().min(1).max(12).default(3),
+  gap: z2.number().int().min(0).max(256).default(24),
+  cardMinHeight: z2.number().int().min(32).max(4096).optional(),
+  cardMaxHeight: z2.number().int().min(32).max(4096).optional(),
+  equalHeight: z2.boolean().default(false)
+}).strict();
+var stackLayoutConfigSchema = z2.object({
+  mode: z2.literal("stack"),
+  direction: z2.enum(["vertical", "horizontal"]).default("vertical"),
+  gap: z2.number().int().min(0).max(256).default(24),
+  alignment: z2.enum(["start", "center", "end", "stretch"]).default("stretch")
+}).strict();
+var manualPositionSchema = z2.object({
+  x: z2.number().int(),
+  y: z2.number().int(),
+  width: z2.number().int().positive().optional(),
+  height: z2.number().int().positive().optional()
+}).strict();
+var manualLayoutConfigSchema = z2.object({
+  mode: z2.literal("manual"),
+  positions: z2.record(z2.string().min(1), manualPositionSchema).default({})
+}).strict();
+var layoutConfigSchema = z2.discriminatedUnion("mode", [
+  autoLayoutConfigSchema,
+  gridLayoutConfigSchema,
+  stackLayoutConfigSchema,
+  manualLayoutConfigSchema
+]);
+var constraintsSchema = z2.object({
+  minContrastRatio: z2.number().min(3).max(21).default(4.5),
+  minFooterSpacing: z2.number().int().min(0).max(256).default(16),
+  checkOverlaps: z2.boolean().default(true),
+  maxTextTruncation: z2.number().min(0).max(1).default(0.1)
+}).strict();
+var headerSchema = z2.object({
+  eyebrow: z2.string().min(1).max(120).optional(),
+  title: z2.string().min(1).max(300),
+  subtitle: z2.string().min(1).max(400).optional(),
+  align: z2.enum(["left", "center", "right"]).default("center"),
+  titleLetterSpacing: z2.number().min(-2).max(20).default(0),
+  titleFontSize: z2.number().min(16).max(96).optional()
+}).strict();
+var footerSchema = z2.object({
+  text: z2.string().min(1).max(300),
+  tagline: z2.string().min(1).max(200).optional()
+}).strict();
+var decoratorSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("rainbow-rule"),
+    y: z2.enum(["after-header", "before-footer", "custom"]).default("after-header"),
+    customY: z2.number().optional(),
+    thickness: z2.number().positive().max(64).default(2),
+    colors: z2.array(colorHexSchema2).min(2).optional(),
+    margin: z2.number().min(0).max(512).default(16)
+  }).strict(),
+  z2.object({
+    type: z2.literal("vignette"),
+    intensity: z2.number().min(0).max(1).default(0.3),
+    color: colorHexSchema2.default("#000000")
+  }).strict(),
+  z2.object({
+    type: z2.literal("gradient-overlay"),
+    gradient: gradientSchema,
+    opacity: z2.number().min(0).max(1).default(0.5)
+  }).strict()
+]);
+var canvasSchema = z2.object({
+  width: z2.number().int().min(320).max(4096).default(defaultCanvas.width),
+  height: z2.number().int().min(180).max(4096).default(defaultCanvas.height),
+  padding: z2.number().int().min(0).max(256).default(defaultCanvas.padding)
+}).strict();
+var themeInputSchema = z2.union([builtInThemeSchema, themeSchema]);
+var designSpecSchema = z2.object({
+  version: z2.literal(2).default(2),
+  canvas: canvasSchema.default(defaultCanvas),
+  theme: themeInputSchema.default("dark"),
+  background: z2.union([colorHexSchema2, gradientSchema]).optional(),
+  header: headerSchema.optional(),
+  elements: z2.array(elementSchema).default([]),
+  footer: footerSchema.optional(),
+  decorators: z2.array(decoratorSchema).default([]),
+  draw: z2.array(drawCommandSchema).max(200).default([]),
+  layout: layoutConfigSchema.optional(),
+  constraints: constraintsSchema.default(defaultConstraints)
+}).strict().transform((spec) => ({
+  ...spec,
+  layout: inferLayout(spec.elements, spec.layout)
+}));
+function deriveSafeFrame(spec) {
+  return {
+    x: spec.canvas.padding,
+    y: spec.canvas.padding,
+    width: spec.canvas.width - spec.canvas.padding * 2,
+    height: spec.canvas.height - spec.canvas.padding * 2
+  };
+}
+function parseDesignSpec(input) {
+  return designSpecSchema.parse(input);
+}
+
+// src/utils/color.ts
+function parseChannel(hex, offset) {
+  return Number.parseInt(hex.slice(offset, offset + 2), 16);
+}
+function parseHexColor(hexColor) {
+  const normalized = hexColor.startsWith("#") ? hexColor.slice(1) : hexColor;
+  if (normalized.length !== 6 && normalized.length !== 8) {
+    throw new Error(`Unsupported color format: ${hexColor}`);
+  }
+  return {
+    r: parseChannel(normalized, 0),
+    g: parseChannel(normalized, 2),
+    b: parseChannel(normalized, 4)
+  };
+}
+function srgbToLinear(channel) {
+  const normalized = channel / 255;
+  if (normalized <= 0.03928) {
+    return normalized / 12.92;
+  }
+  return ((normalized + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance(hexColor) {
+  const rgb = parseHexColor(hexColor);
+  const r = srgbToLinear(rgb.r);
+  const g = srgbToLinear(rgb.g);
+  const b = srgbToLinear(rgb.b);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrastRatio(foreground, background) {
+  const fg = relativeLuminance(foreground);
+  const bg = relativeLuminance(background);
+  const lighter = Math.max(fg, bg);
+  const darker = Math.min(fg, bg);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+// src/qa.ts
+function rectWithin(outer, inner) {
+  return inner.x >= outer.x && inner.y >= outer.y && inner.x + inner.width <= outer.x + outer.width && inner.y + inner.height <= outer.y + outer.height;
+}
+function intersects(a, b) {
+  return !(a.x + a.width <= b.x || b.x + b.width <= a.x || a.y + a.height <= b.y || b.y + b.height <= a.y);
+}
+function canvasRect(spec) {
+  return {
+    x: 0,
+    y: 0,
+    width: spec.canvas.width,
+    height: spec.canvas.height
+  };
+}
+function topLevelElements(elements) {
+  return elements.filter((element) => ["header", "card", "footer"].includes(element.kind));
+}
+function overlapCandidates(elements) {
+  return elements.filter(
+    (element) => [
+      "header",
+      "card",
+      "footer",
+      "flow-node",
+      "terminal",
+      "code-block",
+      "shape",
+      "image",
+      "draw"
+    ].includes(element.kind)
+  );
+}
+function loadMetadataFromString(raw) {
+  return JSON.parse(raw);
+}
+async function readMetadata(path) {
+  const raw = await readFile(resolve(path), "utf8");
+  return loadMetadataFromString(raw);
+}
+async function runQa(options) {
+  const spec = parseDesignSpec(options.spec);
+  const imagePath = resolve(options.imagePath);
+  const expectedSafeFrame = deriveSafeFrame(spec);
+  const expectedCanvas = canvasRect(spec);
+  const imageMetadata = await sharp(imagePath).metadata();
+  const issues = [];
+  const expectedScale = options.metadata?.canvas.scale ?? resolveRenderScale(spec);
+  const expectedWidth = spec.canvas.width * expectedScale;
+  const expectedHeight = spec.canvas.height * expectedScale;
+  if (imageMetadata.width !== expectedWidth || imageMetadata.height !== expectedHeight) {
+    issues.push({
+      code: "DIMENSIONS_MISMATCH",
+      severity: "error",
+      message: `Image dimensions ${imageMetadata.width ?? "?"}x${imageMetadata.height ?? "?"} do not match expected ${expectedWidth}x${expectedHeight}.`,
+      details: {
+        expectedWidth,
+        expectedHeight,
+        actualWidth: imageMetadata.width ?? -1,
+        actualHeight: imageMetadata.height ?? -1
+      }
+    });
+  }
+  const layoutElements = options.metadata?.layout.elements;
+  if (!layoutElements || layoutElements.length === 0) {
+    issues.push({
+      code: "MISSING_LAYOUT",
+      severity: "warning",
+      message: "No layout metadata provided; overlap/clipping checks are partially skipped."
+    });
+  } else {
+    for (const element of layoutElements) {
+      if (element.truncated) {
+        issues.push({
+          code: "TEXT_TRUNCATED",
+          severity: "error",
+          message: `Text for ${element.id} was truncated during render.`,
+          elementId: element.id
+        });
+      }
+      const inCanvas = rectWithin(expectedCanvas, element.bounds);
+      const inSafe = rectWithin(expectedSafeFrame, element.bounds);
+      const requiresSafeFrameContainment = !element.allowOverlap && element.kind !== "draw";
+      if (element.kind === "draw" && !inCanvas) {
+        issues.push({
+          code: "DRAW_OUT_OF_BOUNDS",
+          severity: "warning",
+          message: `Draw command ${element.id} extends beyond canvas bounds.`,
+          elementId: element.id,
+          details: {
+            inCanvas,
+            x: element.bounds.x,
+            y: element.bounds.y,
+            width: element.bounds.width,
+            height: element.bounds.height
+          }
+        });
+      } else if (!inCanvas || requiresSafeFrameContainment && !inSafe) {
+        issues.push({
+          code: "ELEMENT_CLIPPED",
+          severity: "error",
+          message: `Element ${element.id} breaches ${!inCanvas ? "canvas bounds" : "safe frame"}.`,
+          elementId: element.id,
+          details: {
+            inCanvas,
+            inSafeFrame: inSafe,
+            x: element.bounds.x,
+            y: element.bounds.y,
+            width: element.bounds.width,
+            height: element.bounds.height
+          }
+        });
+      }
+      if (element.foregroundColor && element.backgroundColor) {
+        const ratio = contrastRatio(element.foregroundColor, element.backgroundColor);
+        if (ratio < spec.constraints.minContrastRatio) {
+          issues.push({
+            code: "LOW_CONTRAST",
+            severity: "error",
+            message: `Contrast ratio ${ratio.toFixed(2)} for ${element.id} is below threshold ${spec.constraints.minContrastRatio}.`,
+            elementId: element.id,
+            details: {
+              ratio: Number(ratio.toFixed(4)),
+              threshold: spec.constraints.minContrastRatio
+            }
+          });
+        }
+      }
+    }
+    if (spec.constraints.checkOverlaps) {
+      const blocks = overlapCandidates(layoutElements);
+      for (let i = 0; i < blocks.length; i += 1) {
+        for (let j = i + 1; j < blocks.length; j += 1) {
+          const first = blocks[i];
+          const second = blocks[j];
+          if (first.allowOverlap || second.allowOverlap) {
+            continue;
+          }
+          if (intersects(first.bounds, second.bounds)) {
+            const relaxed = first.kind === "draw" || second.kind === "draw";
+            issues.push({
+              code: "ELEMENT_OVERLAP",
+              severity: relaxed ? "warning" : "error",
+              message: `Elements ${first.id} and ${second.id} overlap.${relaxed ? " (Draw overlap is informational.)" : ""}`,
+              elementId: `${first.id}|${second.id}`
+            });
+          }
+        }
+      }
+    }
+    if (spec.footer) {
+      const footer = layoutElements.find((element) => element.id === "footer");
+      const nonFooter = topLevelElements(layoutElements).filter(
+        (element) => element.id !== "footer"
+      );
+      if (footer && nonFooter.length > 0) {
+        const highestBottom = Math.max(
+          ...nonFooter.map((element) => element.bounds.y + element.bounds.height)
+        );
+        const spacing = footer.bounds.y - highestBottom;
+        if (spacing < spec.constraints.minFooterSpacing) {
+          issues.push({
+            code: "FOOTER_SPACING",
+            severity: "error",
+            message: `Footer spacing ${spacing}px is below minimum ${spec.constraints.minFooterSpacing}px.`,
+            elementId: "footer",
+            details: {
+              spacing,
+              min: spec.constraints.minFooterSpacing
+            }
+          });
+        }
+      }
+    }
+    if (spec.header) {
+      const header = layoutElements.find((element) => element.id === "header");
+      if (header?.foregroundColor && header.backgroundColor) {
+        const ratio = contrastRatio(header.foregroundColor, header.backgroundColor);
+        if (ratio < spec.constraints.minContrastRatio) {
+          issues.push({
+            code: "LOW_CONTRAST",
+            severity: "error",
+            message: `Header contrast ratio ${ratio.toFixed(2)} is below threshold ${spec.constraints.minContrastRatio}.`,
+            elementId: "header"
+          });
+        }
+      }
+    }
+    if (!spec.footer && layoutElements.some((element) => element.id === "footer")) {
+      issues.push({
+        code: "FOOTER_SPACING",
+        severity: "warning",
+        message: "Metadata includes a footer element but the spec has no footer."
+      });
+    }
+  }
+  const footerSpacingPx = options.metadata?.layout.elements ? (() => {
+    const footer = options.metadata.layout.elements.find((element) => element.id === "footer");
+    if (!footer) {
+      return void 0;
+    }
+    const nonFooter = topLevelElements(options.metadata.layout.elements).filter(
+      (element) => element.id !== "footer"
+    );
+    if (nonFooter.length === 0) {
+      return void 0;
+    }
+    const highestBottom = Math.max(
+      ...nonFooter.map((element) => element.bounds.y + element.bounds.height)
+    );
+    return footer.bounds.y - highestBottom;
+  })() : void 0;
+  return {
+    pass: issues.every((issue) => issue.severity !== "error"),
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    imagePath,
+    expected: {
+      width: expectedWidth,
+      height: expectedHeight,
+      scale: expectedScale,
+      minContrastRatio: spec.constraints.minContrastRatio,
+      minFooterSpacing: spec.constraints.minFooterSpacing
+    },
+    measured: {
+      ...imageMetadata.width !== void 0 ? { width: imageMetadata.width } : {},
+      ...imageMetadata.height !== void 0 ? { height: imageMetadata.height } : {},
+      ...footerSpacingPx !== void 0 ? { footerSpacingPx } : {}
+    },
+    issues
+  };
+}
+export {
+  readMetadata,
+  runQa
+};