@americano98/peye 0.1.0

package/dist/bin.js

@@ -0,0 +1,3219 @@
+#!/usr/bin/env node
+
+// src/cli/bin.ts
+import { Command } from "commander";
+
+// package.json
+var package_default = {
+  name: "@americano98/peye",
+  version: "0.1.0",
+  description: "Standalone CLI for visual diffing UI screenshots against Figma references.",
+  type: "module",
+  packageManager: "pnpm@10.11.0",
+  bin: {
+    peye: "dist/bin.js"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  files: [
+    "dist"
+  ],
+  engines: {
+    node: ">=22"
+  },
+  scripts: {
+    build: "tsup",
+    clean: "rm -rf coverage dist test-output peye-output",
+    dev: "tsx src/cli/bin.ts",
+    format: "prettier . --write",
+    "format:check": "prettier . --check",
+    lint: "eslint .",
+    "lint:fix": "eslint . --fix",
+    prepack: "pnpm check",
+    test: "vitest run",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit",
+    check: "pnpm format:check && pnpm typecheck && pnpm lint && pnpm test && pnpm build"
+  },
+  keywords: [
+    "cli",
+    "visual-diff",
+    "figma",
+    "playwright",
+    "pixelmatch"
+  ],
+  homepage: "https://github.com/americano98/peye#readme",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/americano98/peye.git"
+  },
+  bugs: {
+    url: "https://github.com/americano98/peye/issues"
+  },
+  license: "MIT",
+  dependencies: {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    commander: "^14.0.3",
+    pixelmatch: "7.1.0",
+    playwright: "1.58.2",
+    sharp: "0.34.5"
+  },
+  devDependencies: {
+    "@eslint/js": "10.0.1",
+    "@types/node": "^22.19.15",
+    eslint: "10.0.3",
+    "eslint-config-prettier": "10.1.8",
+    globals: "17.4.0",
+    prettier: "3.8.1",
+    tsup: "8.5.1",
+    tsx: "4.21.0",
+    typescript: "5.9.3",
+    "typescript-eslint": "8.57.1",
+    vitest: "^4.1.0"
+  }
+};
+
+// src/cli/compare-command.ts
+import path7 from "path";
+
+// src/config/defaults.ts
+var DEFAULT_MODE = "all";
+var DEFAULT_THRESHOLDS = {
+  pass: 0.5,
+  tolerated: 1.5,
+  retry: 5
+};
+var DEFAULT_PIXELMATCH_THRESHOLD = 0.1;
+var DEFAULT_EDGE_THRESHOLD = 96;
+var DEFAULT_MIN_REGION_PIXELS = 9;
+var DEFAULT_CAPTURE_DELAY_MS = 250;
+var DEFAULT_VIEWPORT_HEIGHT = 900;
+var DEFAULT_NAVIGATION_TIMEOUT_MS = 3e4;
+var DEFAULT_RESOURCE_TIMEOUT_MS = 15e3;
+var DEFAULT_FONT_READY_TIMEOUT_MS = 5e3;
+var DEFAULT_REPORT_FINDINGS_LIMIT = 25;
+var DEFAULT_MAX_TEXT_SNIPPET_LENGTH = 80;
+var DEFAULT_MAX_SELECTOR_LENGTH = 120;
+var DEFAULT_MAX_TAG_ROLLUPS = 10;
+var DEFAULT_DOM_OVERLAP_THRESHOLD = 0.3;
+var DEFAULT_CLUSTER_PADDING_PX = 8;
+var DEFAULT_HOTSPOT_CLUSTER_PADDING_PX = 6;
+var DEFAULT_HOTSPOT_LIMIT_PER_FINDING = 5;
+var DEFAULT_FIGMA_SOURCE = "auto";
+var DEFAULT_FIGMA_API_BASE_URL = "https://api.figma.com";
+var DEFAULT_FIGMA_MCP_DESKTOP_URL = "http://127.0.0.1:3845/mcp";
+var DEFAULT_FIGMA_MCP_REMOTE_URL = "https://mcp.figma.com/mcp";
+var DEFAULT_FIGMA_OAUTH_TIMEOUT_MS = 18e4;
+var LAYOUT_EDGE_RATIO_THRESHOLD = 0.35;
+var COLOR_REGION_DELTA_THRESHOLD = 10;
+var STRONG_DIMENSION_DELTA_PX = 40;
+var STRONG_DIMENSION_ASPECT_DELTA = 0.1;
+var HUMAN_REVIEW_MISMATCH_MULTIPLIER = 3;
+var MAX_RGB_DISTANCE = 441.6729559300637;
+
+// src/core/run-compare.ts
+import path6 from "path";
+
+// src/utils/errors.ts
+var AppError = class extends Error {
+  code;
+  exitCode;
+  recommendation;
+  severity;
+  constructor(message, options) {
+    super(message, options?.cause ? { cause: options.cause } : void 0);
+    this.name = "AppError";
+    this.code = options?.code ?? "app_error";
+    this.exitCode = options?.exitCode ?? 1;
+    this.recommendation = options?.recommendation ?? null;
+    this.severity = options?.severity ?? null;
+  }
+};
+function isAppError(error) {
+  return error instanceof AppError;
+}
+function ensureError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(typeof error === "string" ? error : "Unknown error");
+}
+function createFailureReport(params) {
+  const emptyMetrics = {
+    mismatchPixels: 0,
+    mismatchPercent: 0,
+    meanColorDelta: null,
+    maxColorDelta: null,
+    structuralMismatchPercent: null,
+    dimensionMismatch: {
+      widthDelta: 0,
+      heightDelta: 0,
+      aspectRatioDelta: 0,
+      hasMismatch: false
+    },
+    findingsCount: 0,
+    affectedElementCount: 0
+  };
+  return {
+    analysisMode: params.analysisMode,
+    summary: {
+      recommendation: params.recommendation,
+      severity: params.severity,
+      reason: params.reason
+    },
+    inputs: {
+      preview: params.preview,
+      reference: params.reference,
+      viewport: params.viewport,
+      mode: params.mode,
+      fullPage: params.fullPage
+    },
+    images: params.images,
+    metrics: emptyMetrics,
+    rollups: {
+      bySeverity: [],
+      byKind: [],
+      byTag: [],
+      rawRegionCount: 0,
+      findingsCount: 0,
+      affectedElementCount: 0,
+      omittedFindings: 0
+    },
+    findings: [],
+    artifacts: params.artifacts,
+    error: params.error
+  };
+}
+
+// src/utils/severity.ts
+var SEVERITY_RANK = {
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3
+};
+function maxSeverity(values) {
+  if (values.length === 0) {
+    return "low";
+  }
+  return values.reduce(
+    (current, candidate) => SEVERITY_RANK[candidate] > SEVERITY_RANK[current] ? candidate : current
+  );
+}
+function compareSeverityDescending(left, right) {
+  return SEVERITY_RANK[right] - SEVERITY_RANK[left];
+}
+
+// src/analysis/findings.ts
+var FINDING_KIND_ORDER = ["dimension", "mixed", "layout", "color", "pixel"];
+function buildFindingsAnalysis(params) {
+  const totalPixels = params.width * params.height;
+  const draftFindingGroups = params.analysisMode === "dom-elements" ? buildDomFindings(
+    params.rawRegions,
+    params.domSnapshot,
+    params.width,
+    params.height,
+    totalPixels
+  ) : buildVisualClusterFindings(params.rawRegions, totalPixels, params.width, params.height);
+  const sortedGroups = draftFindingGroups.sort(
+    (left, right) => compareDraftFindings(left.finding, right.finding)
+  );
+  const sortedFindings = sortedGroups.map((group) => group.finding);
+  const limitedGroups = sortedGroups.slice(0, DEFAULT_REPORT_FINDINGS_LIMIT);
+  const limitedFindings = limitedGroups.map((group) => group.finding);
+  const affectedElementCount = params.analysisMode === "dom-elements" ? new Set(
+    sortedFindings.map((finding) => finding.element?.selector ?? null).filter((selector) => selector !== null)
+  ).size : 0;
+  return {
+    findings: limitedFindings.map((finding, index) => ({
+      id: `finding-${String(index + 1).padStart(3, "0")}`,
+      ...finding
+    })),
+    rollups: {
+      bySeverity: buildSeverityRollups(sortedFindings),
+      byKind: buildKindRollups(sortedFindings),
+      byTag: params.analysisMode === "dom-elements" ? buildTagRollups(sortedFindings).slice(0, DEFAULT_MAX_TAG_ROLLUPS) : [],
+      rawRegionCount: params.rawRegions.length,
+      findingsCount: sortedFindings.length,
+      affectedElementCount,
+      omittedFindings: Math.max(0, sortedFindings.length - limitedFindings.length)
+    },
+    metrics: {
+      findingsCount: sortedFindings.length,
+      affectedElementCount
+    },
+    visuals: sortedGroups.map((group) => {
+      const primaryBox = group.finding.element?.bbox ?? group.finding.bbox;
+      return {
+        severity: group.finding.severity,
+        primaryBox,
+        hotspotBoxes: group.finding.hotspots
+      };
+    })
+  };
+}
+function buildDomFindings(rawRegions, domSnapshot, width, height, totalPixels) {
+  if (!domSnapshot) {
+    throw new AppError("Preview URL capture did not produce a DOM snapshot.", {
+      exitCode: 3,
+      recommendation: "needs_human_review",
+      severity: "high",
+      code: "dom_snapshot_missing"
+    });
+  }
+  if (rawRegions.length === 0) {
+    return [];
+  }
+  const candidates = buildDomCandidates(domSnapshot, width, height);
+  const regionsByElement = /* @__PURE__ */ new Map();
+  const elementsById = new Map(candidates.map((element) => [element.id, element]));
+  for (const region of rawRegions) {
+    const element = resolveDomElementForRegion(region, candidates);
+    const existing = regionsByElement.get(element.id);
+    if (existing) {
+      existing.push(region);
+    } else {
+      regionsByElement.set(element.id, [region]);
+    }
+  }
+  return Array.from(regionsByElement.entries(), ([elementId, regions]) => {
+    const element = elementsById.get(elementId);
+    if (!element) {
+      throw new AppError(`DOM element snapshot missing for finding group ${elementId}.`, {
+        exitCode: 3,
+        recommendation: "needs_human_review",
+        severity: "high",
+        code: "dom_snapshot_element_missing"
+      });
+    }
+    return {
+      finding: buildDraftFinding({
+        source: "dom-element",
+        regions,
+        totalPixels,
+        element,
+        canvasWidth: width,
+        canvasHeight: height
+      }),
+      regions
+    };
+  });
+}
+function buildVisualClusterFindings(rawRegions, totalPixels, width, height) {
+  if (rawRegions.length === 0) {
+    return [];
+  }
+  const clusters = clusterRegions(rawRegions);
+  return clusters.map((cluster) => ({
+    finding: buildDraftFinding({
+      source: "visual-cluster",
+      regions: cluster,
+      totalPixels,
+      element: null,
+      canvasWidth: width,
+      canvasHeight: height
+    }),
+    regions: cluster
+  }));
+}
+function buildDraftFinding(params) {
+  const bbox = unionRegionBoxes(params.regions);
+  const mismatchPixels = params.regions.reduce((sum, region) => sum + region.pixelCount, 0);
+  const kind = aggregateKind(params.regions);
+  const elementReport = params.element ? toElementReport(params.element) : null;
+  const primaryBox = elementReport?.bbox ?? bbox;
+  return {
+    source: params.source,
+    kind,
+    severity: maxSeverity(params.regions.map((region) => region.severity)),
+    summary: buildFindingSummary(kind, elementReport?.tag ?? null),
+    bbox,
+    regionCount: params.regions.length,
+    mismatchPixels,
+    mismatchPercentOfCanvas: params.totalPixels === 0 ? 0 : Number((mismatchPixels / params.totalPixels * 100).toFixed(4)),
+    issueTypes: issueTypesForKind(kind),
+    signals: buildFindingSignals({
+      kind,
+      bbox,
+      element: params.element,
+      canvasWidth: params.canvasWidth,
+      canvasHeight: params.canvasHeight
+    }),
+    hotspots: buildHotspotBoxes(params.regions, primaryBox),
+    element: elementReport
+  };
+}
+function buildDomCandidates(domSnapshot, width, height) {
+  const root = {
+    ...domSnapshot.root,
+    bbox: {
+      x: 0,
+      y: 0,
+      width,
+      height
+    }
+  };
+  return [root, ...domSnapshot.elements];
+}
+function resolveDomElementForRegion(region, candidates) {
+  const centerX = region.x + region.width / 2;
+  const centerY = region.y + region.height / 2;
+  const containing = candidates.filter(
+    (candidate) => containsPoint(candidate.bbox, centerX, centerY)
+  );
+  if (containing.length > 0) {
+    return containing.sort(compareDomCandidates)[0];
+  }
+  const regionBox = {
+    x: region.x,
+    y: region.y,
+    width: region.width,
+    height: region.height
+  };
+  let bestCandidate = null;
+  let bestOverlap = 0;
+  for (const candidate of candidates) {
+    const overlap = overlapRatio(regionBox, candidate.bbox);
+    if (overlap > bestOverlap) {
+      bestCandidate = candidate;
+      bestOverlap = overlap;
+      continue;
+    }
+    if (overlap === bestOverlap && bestCandidate && compareDomCandidates(candidate, bestCandidate) < 0) {
+      bestCandidate = candidate;
+    }
+  }
+  if (bestCandidate && bestOverlap >= DEFAULT_DOM_OVERLAP_THRESHOLD) {
+    return bestCandidate;
+  }
+  throw new AppError(
+    `Could not assign mismatch region at (${region.x}, ${region.y}, ${region.width}x${region.height}) to a DOM element.`,
+    {
+      exitCode: 3,
+      recommendation: "needs_human_review",
+      severity: "high",
+      code: "dom_region_assignment_failed"
+    }
+  );
+}
+function compareDomCandidates(left, right) {
+  if (left.depth !== right.depth) {
+    return right.depth - left.depth;
+  }
+  const leftArea = left.bbox.width * left.bbox.height;
+  const rightArea = right.bbox.width * right.bbox.height;
+  if (leftArea !== rightArea) {
+    return leftArea - rightArea;
+  }
+  return left.selector.localeCompare(right.selector);
+}
+function clusterRegions(rawRegions, padding = DEFAULT_CLUSTER_PADDING_PX) {
+  const visited = new Uint8Array(rawRegions.length);
+  const clusters = [];
+  for (let index = 0; index < rawRegions.length; index += 1) {
+    if (visited[index] === 1) {
+      continue;
+    }
+    visited[index] = 1;
+    const queue = [index];
+    const cluster = [];
+    while (queue.length > 0) {
+      const currentIndex = queue.shift();
+      if (currentIndex === void 0) {
+        break;
+      }
+      const currentRegion = rawRegions[currentIndex];
+      cluster.push(currentRegion);
+      for (let candidateIndex = 0; candidateIndex < rawRegions.length; candidateIndex += 1) {
+        if (visited[candidateIndex] === 1) {
+          continue;
+        }
+        if (expandedBoxesIntersect(currentRegion, rawRegions[candidateIndex], padding)) {
+          visited[candidateIndex] = 1;
+          queue.push(candidateIndex);
+        }
+      }
+    }
+    clusters.push(cluster);
+  }
+  return clusters;
+}
+function expandedBoxesIntersect(left, right, padding) {
+  return boxesIntersect(expandBox(left, padding), expandBox(right, padding));
+}
+function expandBox(box, padding) {
+  return {
+    x: box.x - padding,
+    y: box.y - padding,
+    width: box.width + padding * 2,
+    height: box.height + padding * 2
+  };
+}
+function boxesIntersect(left, right) {
+  return !(left.x + left.width < right.x || right.x + right.width < left.x || left.y + left.height < right.y || right.y + right.height < left.y);
+}
+function containsPoint(box, x, y) {
+  return x >= box.x && x <= box.x + box.width && y >= box.y && y <= box.y + box.height;
+}
+function overlapRatio(left, right) {
+  const intersectionWidth = Math.min(left.x + left.width, right.x + right.width) - Math.max(left.x, right.x);
+  const intersectionHeight = Math.min(left.y + left.height, right.y + right.height) - Math.max(left.y, right.y);
+  if (intersectionWidth <= 0 || intersectionHeight <= 0) {
+    return 0;
+  }
+  const regionArea = Math.max(1, left.width * left.height);
+  return intersectionWidth * intersectionHeight / regionArea;
+}
+function unionRegionBoxes(regions) {
+  const minX = Math.min(...regions.map((region) => region.x));
+  const minY = Math.min(...regions.map((region) => region.y));
+  const maxX = Math.max(...regions.map((region) => region.x + region.width));
+  const maxY = Math.max(...regions.map((region) => region.y + region.height));
+  return {
+    x: minX,
+    y: minY,
+    width: maxX - minX,
+    height: maxY - minY
+  };
+}
+function buildHotspotBoxes(regions, primaryBox) {
+  if (regions.length <= 1) {
+    return [];
+  }
+  return clusterRegions(regions, DEFAULT_HOTSPOT_CLUSTER_PADDING_PX).map((cluster) => ({
+    bbox: unionRegionBoxes(cluster),
+    mismatchPixels: cluster.reduce((sum, region) => sum + region.pixelCount, 0)
+  })).filter(({ bbox }) => !isNearlySameBox(bbox, primaryBox)).sort((left, right) => {
+    if (left.mismatchPixels !== right.mismatchPixels) {
+      return right.mismatchPixels - left.mismatchPixels;
+    }
+    if (left.bbox.y !== right.bbox.y) {
+      return left.bbox.y - right.bbox.y;
+    }
+    return left.bbox.x - right.bbox.x;
+  }).slice(0, DEFAULT_HOTSPOT_LIMIT_PER_FINDING).map(({ bbox }) => bbox);
+}
+function isNearlySameBox(left, right) {
+  const leftArea = Math.max(1, left.width * left.height);
+  const rightArea = Math.max(1, right.width * right.height);
+  const areaRatio = Math.min(leftArea, rightArea) / Math.max(leftArea, rightArea);
+  return areaRatio >= 0.9 && overlapRatio(left, right) >= 0.9;
+}
+function aggregateKind(regions) {
+  const kinds = new Set(regions.map((region) => region.kind));
+  if (kinds.has("dimension")) {
+    return "dimension";
+  }
+  if (kinds.has("mixed")) {
+    return "mixed";
+  }
+  if (kinds.has("layout") && (kinds.has("color") || kinds.has("pixel"))) {
+    return "mixed";
+  }
+  if (kinds.has("layout")) {
+    return "layout";
+  }
+  if (kinds.has("color")) {
+    return "color";
+  }
+  return "pixel";
+}
+function buildFindingSummary(kind, tag) {
+  const subject = tag ? `Element <${tag}>` : "Visual cluster";
+  switch (kind) {
+    case "dimension":
+      return `${subject} is missing content, has extra content, or was captured at the wrong canvas size.`;
+    case "layout":
+      return `${subject} differs in position, spacing, or alignment.`;
+    case "color":
+      return `${subject} differs in color or visual styling.`;
+    case "mixed":
+      return `${subject} differs in both layout and styling.`;
+    case "pixel":
+    default:
+      return `${subject} differs in rendering or fine-grained styling.`;
+  }
+}
+function issueTypesForKind(kind) {
+  switch (kind) {
+    case "dimension":
+      return ["missing_or_extra", "size"];
+    case "layout":
+      return ["position", "spacing"];
+    case "color":
+      return ["color", "style"];
+    case "mixed":
+      return ["position", "spacing", "style"];
+    case "pixel":
+    default:
+      return ["style"];
+  }
+}
+function buildFindingSignals(params) {
+  const signals = [];
+  const textClippingSignal = buildTextClippingSignal(params.element);
+  if (textClippingSignal) {
+    signals.push(textClippingSignal);
+  }
+  const captureCropSignal = buildCaptureCropSignal(params.element);
+  if (captureCropSignal) {
+    signals.push(captureCropSignal);
+  } else {
+    const viewportSignal = buildViewportMismatchSignal(
+      params.kind,
+      params.bbox,
+      params.canvasWidth,
+      params.canvasHeight
+    );
+    if (viewportSignal) {
+      signals.push(viewportSignal);
+    }
+  }
+  return signals;
+}
+function buildTextClippingSignal(element) {
+  if (!element?.textSnippet || !element.textMetrics) {
+    return null;
+  }
+  const { textMetrics } = element;
+  const hasOverflowX = textMetrics.scrollWidth > textMetrics.clientWidth + 1;
+  const hasOverflowY = textMetrics.scrollHeight > textMetrics.clientHeight + 1;
+  const clipsX = hasOverflowX && (textMetrics.overflowX === "hidden" || textMetrics.overflowX === "clip" || textMetrics.textOverflow === "ellipsis");
+  const lineClampActive = textMetrics.lineClamp !== null && textMetrics.lineClamp !== "" && textMetrics.lineClamp !== "none" && textMetrics.lineClamp !== "0" && textMetrics.lineClamp !== "normal";
+  const clipsY = hasOverflowY && (textMetrics.overflowY === "hidden" || textMetrics.overflowY === "clip" || lineClampActive);
+  if (!clipsX && !clipsY) {
+    return null;
+  }
+  const axis = clipsX && clipsY ? "horizontal and vertical axes" : clipsX ? "horizontal axis" : "vertical axis";
+  return {
+    code: "probable_text_clipping",
+    confidence: lineClampActive || clipsX && clipsY ? "high" : "medium",
+    message: `Text content likely overflows the element bounds and is being clipped on the ${axis}.`
+  };
+}
+function buildCaptureCropSignal(element) {
+  if (!element || element.captureClippedEdges.length === 0) {
+    return null;
+  }
+  return {
+    code: "possible_capture_crop",
+    confidence: "high",
+    message: `Element bounds were clipped by the preview capture on the ${formatEdgeList(element.captureClippedEdges)} edge(s); check selector scope and capture framing.`
+  };
+}
+function buildViewportMismatchSignal(kind, bbox, canvasWidth, canvasHeight) {
+  if (kind !== "dimension") {
+    return null;
+  }
+  const touchingEdges = boxEdgesAgainstCanvas(bbox, canvasWidth, canvasHeight);
+  if (touchingEdges.length === 0) {
+    return null;
+  }
+  return {
+    code: "possible_viewport_mismatch",
+    confidence: "medium",
+    message: `Dimension mismatch reaches the ${formatEdgeList(touchingEdges)} edge(s) of the comparison canvas; verify viewport, selected frame, and capture target.`
+  };
+}
+function boxEdgesAgainstCanvas(box, canvasWidth, canvasHeight) {
+  const edges = [];
+  if (box.y <= 0) {
+    edges.push("top");
+  }
+  if (box.x + box.width >= canvasWidth) {
+    edges.push("right");
+  }
+  if (box.y + box.height >= canvasHeight) {
+    edges.push("bottom");
+  }
+  if (box.x <= 0) {
+    edges.push("left");
+  }
+  return edges;
+}
+function formatEdgeList(edges) {
+  if (edges.length === 1) {
+    return edges[0];
+  }
+  if (edges.length === 2) {
+    return `${edges[0]} and ${edges[1]}`;
+  }
+  return `${edges.slice(0, -1).join(", ")}, and ${edges[edges.length - 1]}`;
+}
+function toElementReport(element) {
+  return {
+    tag: element.tag,
+    selector: element.selector,
+    role: element.role,
+    textSnippet: element.textSnippet,
+    bbox: element.bbox
+  };
+}
+function buildSeverityRollups(findings) {
+  const severityCounts = /* @__PURE__ */ new Map();
+  for (const finding of findings) {
+    severityCounts.set(finding.severity, (severityCounts.get(finding.severity) ?? 0) + 1);
+  }
+  return Array.from(severityCounts.entries()).map(([severity, count]) => ({ severity, count })).sort((left, right) => compareSeverityDescending(left.severity, right.severity));
+}
+function buildKindRollups(findings) {
+  const kindCounts = /* @__PURE__ */ new Map();
+  for (const finding of findings) {
+    kindCounts.set(finding.kind, (kindCounts.get(finding.kind) ?? 0) + 1);
+  }
+  return Array.from(kindCounts.entries()).map(([kind, count]) => ({ kind, count })).sort(
+    (left, right) => FINDING_KIND_ORDER.indexOf(left.kind) - FINDING_KIND_ORDER.indexOf(right.kind)
+  );
+}
+function buildTagRollups(findings) {
+  const tagCounts = /* @__PURE__ */ new Map();
+  for (const finding of findings) {
+    const tag = finding.element?.tag;
+    if (!tag) {
+      continue;
+    }
+    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+  }
+  return Array.from(tagCounts.entries()).map(([tag, count]) => ({ tag, count })).sort((left, right) => {
+    if (left.count !== right.count) {
+      return right.count - left.count;
+    }
+    return left.tag.localeCompare(right.tag);
+  });
+}
+function compareDraftFindings(left, right) {
+  const severityOrder = compareSeverityDescending(left.severity, right.severity);
+  if (severityOrder !== 0) {
+    return severityOrder;
+  }
+  if (left.mismatchPixels !== right.mismatchPixels) {
+    return right.mismatchPixels - left.mismatchPixels;
+  }
+  if (left.bbox.y !== right.bbox.y) {
+    return left.bbox.y - right.bbox.y;
+  }
+  if (left.bbox.x !== right.bbox.x) {
+    return left.bbox.x - right.bbox.x;
+  }
+  return left.summary.localeCompare(right.summary);
+}
+
+// src/analysis/recommendation.ts
+function decideRecommendation(params) {
+  const { metrics, thresholds, findings } = params;
+  const highestFindingSeverity = maxSeverity(findings.map((finding) => finding.severity));
+  const strongDimensionMismatch = hasStrongDimensionMismatch(metrics);
+  if (strongDimensionMismatch || metrics.mismatchPercent > thresholds.retry * HUMAN_REVIEW_MISMATCH_MULTIPLIER) {
+    return {
+      recommendation: "needs_human_review",
+      severity: maxSeverity([
+        highestFindingSeverity,
+        strongDimensionMismatch ? "critical" : "high"
+      ]),
+      reason: strongDimensionMismatch ? "Reference and preview dimensions diverge too much for a reliable automated verdict." : `Mismatch percentage ${metrics.mismatchPercent.toFixed(2)}% is too large for an automated fix recommendation.`
+    };
+  }
+  if (metrics.mismatchPercent <= thresholds.pass && highestFindingSeverity === "low") {
+    return {
+      recommendation: "pass",
+      severity: "low",
+      reason: `Mismatch is ${metrics.mismatchPercent.toFixed(2)}%, within the strict pass threshold.`
+    };
+  }
+  if (metrics.mismatchPercent <= thresholds.tolerated && highestFindingSeverity === "low") {
+    return {
+      recommendation: "pass_with_tolerated_differences",
+      severity: "low",
+      reason: `Mismatch is ${metrics.mismatchPercent.toFixed(2)}%, within the tolerated threshold.`
+    };
+  }
+  if (metrics.mismatchPercent <= thresholds.retry || highestFindingSeverity === "medium" || highestFindingSeverity === "high") {
+    return {
+      recommendation: "retry_fix",
+      severity: highestFindingSeverity === "critical" ? "high" : highestFindingSeverity,
+      reason: `Mismatch is ${metrics.mismatchPercent.toFixed(2)}%; localized issues were detected and should be fixed before retrying.`
+    };
+  }
+  return {
+    recommendation: "needs_human_review",
+    severity: maxSeverity([highestFindingSeverity, "high"]),
+    reason: `Mismatch is ${metrics.mismatchPercent.toFixed(2)}% and exceeds the retry threshold.`
+  };
+}
+function hasStrongDimensionMismatch(metrics) {
+  return metrics.dimensionMismatch.hasMismatch && (Math.abs(metrics.dimensionMismatch.widthDelta) >= STRONG_DIMENSION_DELTA_PX || Math.abs(metrics.dimensionMismatch.heightDelta) >= STRONG_DIMENSION_DELTA_PX || metrics.dimensionMismatch.aspectRatioDelta >= STRONG_DIMENSION_ASPECT_DELTA);
+}
+
+// src/capture/playwright-capture.ts
+import { unlink } from "fs/promises";
+import path2 from "path";
+import { chromium } from "playwright";
+
+// src/io/image.ts
+import { writeFile } from "fs/promises";
+import path from "path";
+import sharp from "sharp";
+async function normalizeImageToPng(inputPath, outputPath) {
+  return normalizeSourceToPng(inputPath, outputPath, `Failed to normalize image: ${inputPath}`);
+}
+async function bufferToNormalizedPng(buffer, outputPath, options) {
+  return normalizeSourceToPng(
+    buffer,
+    outputPath,
+    "Failed to normalize in-memory image buffer.",
+    options
+  );
+}
+async function loadNormalizedImage(imagePath) {
+  try {
+    const { data, info } = await sharp(imagePath).rotate().ensureAlpha().toColorspace("srgb").raw().toBuffer({ resolveWithObject: true });
+    return {
+      width: info.width,
+      height: info.height,
+      data: new Uint8ClampedArray(data)
+    };
+  } catch (error) {
+    throw new AppError(`Failed to load normalized image data: ${imagePath}`, {
+      code: "image_load_failed",
+      cause: error
+    });
+  }
+}
+function padImageToCanvas(image, width, height) {
+  if (image.width === width && image.height === height) {
+    return image;
+  }
+  const target = new Uint8ClampedArray(width * height * 4);
+  for (let y = 0; y < image.height; y += 1) {
+    const sourceOffset = y * image.width * 4;
+    const targetOffset = y * width * 4;
+    target.set(image.data.subarray(sourceOffset, sourceOffset + image.width * 4), targetOffset);
+  }
+  return {
+    width,
+    height,
+    data: target
+  };
+}
+async function writeRawRgbaPng(outputPath, data, width, height) {
+  try {
+    await sharp(Buffer.from(data), {
+      raw: {
+        width,
+        height,
+        channels: 4
+      }
+    }).png().toFile(outputPath);
+  } catch (error) {
+    throw new AppError(`Failed to write PNG artifact: ${outputPath}`, {
+      code: "artifact_write_failed",
+      cause: error
+    });
+  }
+}
+async function normalizeSourceToPng(input, outputPath, errorMessage, options) {
+  const resolvedOutputPath = path.resolve(outputPath);
+  try {
+    let pipeline = sharp(input).rotate().ensureAlpha().toColorspace("srgb");
+    if (options?.resizeTo) {
+      pipeline = pipeline.resize(options.resizeTo.width, options.resizeTo.height, {
+        fit: "fill",
+        kernel: sharp.kernel.lanczos3
+      });
+    }
+    const { data, info } = await pipeline.png().toBuffer({ resolveWithObject: true });
+    if (!info.width || !info.height) {
+      throw new AppError(`Could not read normalized image dimensions for ${resolvedOutputPath}`, {
+        code: "image_dimensions_missing"
+      });
+    }
+    await writeFile(resolvedOutputPath, data);
+    return {
+      path: resolvedOutputPath,
+      width: info.width,
+      height: info.height
+    };
+  } catch (error) {
+    if (error instanceof AppError) {
+      throw error;
+    }
+    throw new AppError(`${errorMessage}: ${ensureError(error).message}`, {
+      code: "image_normalization_failed",
+      cause: error
+    });
+  }
+}
+
+// src/capture/playwright-capture.ts
+async function materializePreviewImage(preview, outputPath, fullPage) {
+  if (preview.kind === "path") {
+    try {
+      const normalized = await normalizeImageToPng(preview.resolved, outputPath);
+      return {
+        ...normalized,
+        analysisMode: "visual-clusters",
+        domSnapshot: null
+      };
+    } catch (error) {
+      throw new AppError(
+        `Failed to normalize preview image: ${preview.resolved}. ${ensureError(error).message}`,
+        {
+          code: "preview_image_normalization_failed",
+          cause: error
+        }
+      );
+    }
+  }
+  const temporaryCapturePath = buildTemporaryCapturePath(outputPath);
+  const browser = await chromium.launch({ headless: true });
+  let domSnapshot;
+  try {
+    const page = await browser.newPage({
+      viewport: preview.viewport,
+      deviceScaleFactor: 1
+    });
+    await navigateForCapture(page, preview.resolved);
+    await waitForCaptureStability(page);
+    if (preview.selector !== null) {
+      domSnapshot = await captureSelectorScreenshot(page, preview.selector, temporaryCapturePath);
+    } else {
+      domSnapshot = await collectPageDomSnapshot(page, fullPage);
+      await page.screenshot({
+        path: temporaryCapturePath,
+        animations: "disabled",
+        caret: "hide",
+        fullPage,
+        scale: "css",
+        type: "png"
+      });
+    }
+  } finally {
+    await browser.close();
+  }
+  try {
+    const normalized = await normalizeImageToPng(temporaryCapturePath, outputPath);
+    return {
+      ...normalized,
+      analysisMode: "dom-elements",
+      domSnapshot
+    };
+  } catch (error) {
+    throw new AppError(
+      `Failed to normalize captured preview image: ${temporaryCapturePath}. ${ensureError(error).message}`,
+      {
+        code: "preview_capture_normalization_failed",
+        cause: error
+      }
+    );
+  } finally {
+    await unlink(temporaryCapturePath).catch(() => void 0);
+  }
+}
+async function navigateForCapture(page, url) {
+  try {
+    await page.goto(url, {
+      waitUntil: "networkidle",
+      timeout: DEFAULT_NAVIGATION_TIMEOUT_MS
+    });
+  } catch {
+    await page.goto(url, {
+      waitUntil: "load",
+      timeout: DEFAULT_NAVIGATION_TIMEOUT_MS
+    });
+  }
+}
+async function waitForCaptureStability(page) {
+  await page.evaluate(
+    async ({ fontTimeoutMs }) => {
+      const fonts = document.fonts;
+      if (!fonts) {
+        return;
+      }
+      await Promise.race([
+        fonts.ready,
+        new Promise((resolve) => {
+          window.setTimeout(resolve, fontTimeoutMs);
+        })
+      ]);
+    },
+    { fontTimeoutMs: DEFAULT_FONT_READY_TIMEOUT_MS }
+  ).catch(() => void 0);
+  await page.waitForTimeout(DEFAULT_CAPTURE_DELAY_MS);
+}
+async function captureSelectorScreenshot(page, selector, outputPath) {
+  try {
+    const locator = page.locator(selector).first();
+    await locator.waitFor({ state: "visible", timeout: DEFAULT_NAVIGATION_TIMEOUT_MS });
+    await locator.scrollIntoViewIfNeeded();
+    const domSnapshot = await collectSelectorDomSnapshot(locator);
+    await locator.screenshot({
+      path: outputPath,
+      animations: "disabled",
+      caret: "hide",
+      scale: "css",
+      type: "png"
+    });
+    return domSnapshot;
+  } catch (error) {
+    throw new AppError(
+      `Preview selector could not be captured: ${selector}. ${ensureError(error).message}`,
+      {
+        exitCode: 3,
+        recommendation: "needs_human_review",
+        severity: "high",
+        code: "preview_selector_capture_failed",
+        cause: error
+      }
+    );
+  }
+}
+function buildTemporaryCapturePath(outputPath) {
+  const parsedPath = path2.parse(outputPath);
+  return path2.join(
+    parsedPath.dir,
+    `${parsedPath.name}.capture-${process.pid}-${Date.now()}${parsedPath.ext || ".png"}`
+  );
+}
+async function collectSelectorDomSnapshot(locator) {
+  return locator.evaluate(
+    (root, { maxSelectorLength, maxTextLength }) => {
+      const excludedTags = /* @__PURE__ */ new Set(["script", "style", "noscript", "meta", "link", "head"]);
+      const inlineNoiseTags = /* @__PURE__ */ new Set(["span", "strong", "em", "b", "i", "u", "small"]);
+      const semanticTags = /* @__PURE__ */ new Set([
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "p",
+        "button",
+        "a",
+        "img",
+        "svg",
+        "video",
+        "canvas",
+        "input",
+        "textarea",
+        "select",
+        "label",
+        "li",
+        "section",
+        "article",
+        "nav",
+        "main",
+        "aside",
+        "header",
+        "footer"
+      ]);
+      const rootRect = root.getBoundingClientRect();
+      const captureBounds = {
+        x: 0,
+        y: 0,
+        width: Math.max(1, Math.round(rootRect.width)),
+        height: Math.max(1, Math.round(rootRect.height))
+      };
+      const normalizeWhitespace = (value) => value.replace(/\s+/g, " ").trim();
+      const clipValue = (value, limit) => value.length <= limit ? value : `${value.slice(0, Math.max(0, limit - 1))}\u2026`;
+      const toTag = (element) => element.tagName.toLowerCase();
+      const isTransparent = (value) => value === "transparent" || value === "rgba(0, 0, 0, 0)" || value === "rgba(0,0,0,0)";
+      const hasVisibleBorder = (style) => Number.parseFloat(style.borderTopWidth) > 0 || Number.parseFloat(style.borderRightWidth) > 0 || Number.parseFloat(style.borderBottomWidth) > 0 || Number.parseFloat(style.borderLeftWidth) > 0;
+      const hasPaintedBox = (style) => style.backgroundImage !== "none" || !isTransparent(style.backgroundColor) || hasVisibleBorder(style) || style.boxShadow !== "none";
+      const escapeIdentifier = (value) => typeof CSS !== "undefined" && typeof CSS.escape === "function" ? CSS.escape(value) : value;
+      const directTextSnippet = (element) => {
+        const text = element instanceof HTMLElement ? element.innerText || element.textContent || "" : element.textContent || "";
+        return clipValue(normalizeWhitespace(text), maxTextLength);
+      };
+      const depthFromRoot = (element) => {
+        let depth = 0;
+        let current = element;
+        while (current && current !== root) {
+          depth += 1;
+          current = current.parentElement;
+        }
+        return depth;
+      };
+      const nthOfType = (element) => {
+        let index = 1;
+        let sibling = element.previousElementSibling;
+        while (sibling) {
+          if (sibling.tagName === element.tagName) {
+            index += 1;
+          }
+          sibling = sibling.previousElementSibling;
+        }
+        return index;
+      };
+      const segmentFor = (element) => {
+        const tag = toTag(element);
+        if (element.id) {
+          return `${tag}#${escapeIdentifier(element.id)}`;
+        }
+        const classNames = Array.from(element.classList).filter((className) => /^[A-Za-z_][\w-]*$/u.test(className)).slice(0, 2);
+        if (classNames.length > 0) {
+          return `${tag}.${classNames.map((className) => escapeIdentifier(className)).join(".")}`;
+        }
+        return `${tag}:nth-of-type(${nthOfType(element)})`;
+      };
+      const buildSelector = (element) => {
+        if (element === root) {
+          return clipValue(segmentFor(element), maxSelectorLength);
+        }
+        const parts = [];
+        let current = element;
+        while (current && parts.length < 3) {
+          parts.unshift(segmentFor(current));
+          if (current === root) {
+            break;
+          }
+          current = current.parentElement;
+        }
+        return clipValue(parts.join(" > "), maxSelectorLength);
+      };
+      const clipBoxToBounds = (box, bounds) => {
+        const left = Math.max(bounds.x, box.x);
+        const top = Math.max(bounds.y, box.y);
+        const right = Math.min(bounds.x + bounds.width, box.x + box.width);
+        const bottom = Math.min(bounds.y + bounds.height, box.y + box.height);
+        if (right <= left || bottom <= top) {
+          return null;
+        }
+        return {
+          x: Math.round(left),
+          y: Math.round(top),
+          width: Math.round(right - left),
+          height: Math.round(bottom - top)
+        };
+      };
+      const clippedEdgesForBox = (box, bounds) => {
+        const edges = [];
+        if (box.y < bounds.y) {
+          edges.push("top");
+        }
+        if (box.x + box.width > bounds.x + bounds.width) {
+          edges.push("right");
+        }
+        if (box.y + box.height > bounds.y + bounds.height) {
+          edges.push("bottom");
+        }
+        if (box.x < bounds.x) {
+          edges.push("left");
+        }
+        return edges;
+      };
+      const toRelativeBox = (element) => {
+        const rect = element.getBoundingClientRect();
+        const rawBox = {
+          x: rect.left - rootRect.left,
+          y: rect.top - rootRect.top,
+          width: rect.width,
+          height: rect.height
+        };
+        const bbox = clipBoxToBounds(rawBox, captureBounds);
+        if (!bbox) {
+          return null;
+        }
+        return {
+          bbox,
+          captureClippedEdges: clippedEdgesForBox(rawBox, captureBounds)
+        };
+      };
+      const isVisible = (element) => {
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) {
+          return false;
+        }
+        const style = window.getComputedStyle(element);
+        return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0" && style.pointerEvents !== "none";
+      };
+      const isMeaningful = (element) => {
+        if (element === root) {
+          return true;
+        }
+        const tag = toTag(element);
+        if (excludedTags.has(tag) || inlineNoiseTags.has(tag)) {
+          return false;
+        }
+        if (!isVisible(element)) {
+          return false;
+        }
+        const style = window.getComputedStyle(element);
+        const hasText = directTextSnippet(element).length > 0;
+        const hasRole = Boolean(element.getAttribute("role"));
+        return hasText || hasRole || semanticTags.has(tag) || hasPaintedBox(style) || element.children.length === 0;
+      };
+      const buildSnapshotElement = (element) => {
+        const boxInfo = toRelativeBox(element);
+        if (!boxInfo) {
+          return null;
+        }
+        const style = window.getComputedStyle(element);
+        const textMetrics = element instanceof HTMLElement ? {
+          clientWidth: Math.round(element.clientWidth),
+          clientHeight: Math.round(element.clientHeight),
+          scrollWidth: Math.round(element.scrollWidth),
+          scrollHeight: Math.round(element.scrollHeight),
+          overflowX: style.overflowX,
+          overflowY: style.overflowY,
+          textOverflow: style.textOverflow,
+          whiteSpace: style.whiteSpace,
+          lineClamp: style.getPropertyValue("-webkit-line-clamp") || style.getPropertyValue("line-clamp") || null
+        } : null;
+        return {
+          id: buildSelector(element),
+          tag: toTag(element),
+          selector: buildSelector(element),
+          role: element.getAttribute("role"),
+          textSnippet: directTextSnippet(element) || null,
+          bbox: boxInfo.bbox,
+          depth: depthFromRoot(element),
+          captureClippedEdges: boxInfo.captureClippedEdges,
+          textMetrics
+        };
+      };
+      const allElements = [root, ...Array.from(root.querySelectorAll("*"))].filter((element) => isMeaningful(element)).map((element) => buildSnapshotElement(element)).filter((element) => element !== null);
+      const [snapshotRoot, ...elements] = allElements;
+      if (!snapshotRoot) {
+        throw new Error("No meaningful DOM elements were found inside the selector capture.");
+      }
+      return {
+        root: snapshotRoot,
+        elements
+      };
+    },
+    {
+      maxSelectorLength: DEFAULT_MAX_SELECTOR_LENGTH,
+      maxTextLength: DEFAULT_MAX_TEXT_SNIPPET_LENGTH
+    }
+  );
+}
+async function collectPageDomSnapshot(page, fullPage) {
+  return page.evaluate(
+    ({ fullPageCapture, maxSelectorLength, maxTextLength }) => {
+      const excludedTags = /* @__PURE__ */ new Set(["script", "style", "noscript", "meta", "link", "head"]);
+      const inlineNoiseTags = /* @__PURE__ */ new Set(["span", "strong", "em", "b", "i", "u", "small"]);
+      const semanticTags = /* @__PURE__ */ new Set([
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "p",
+        "button",
+        "a",
+        "img",
+        "svg",
+        "video",
+        "canvas",
+        "input",
+        "textarea",
+        "select",
+        "label",
+        "li",
+        "section",
+        "article",
+        "nav",
+        "main",
+        "aside",
+        "header",
+        "footer"
+      ]);
+      const root = document.body ?? document.documentElement;
+      const captureBounds = fullPageCapture ? {
+        x: 0,
+        y: 0,
+        width: Math.max(
+          document.documentElement.scrollWidth,
+          document.body?.scrollWidth ?? 0,
+          window.innerWidth
+        ),
+        height: Math.max(
+          document.documentElement.scrollHeight,
+          document.body?.scrollHeight ?? 0,
+          window.innerHeight
+        )
+      } : {
+        x: 0,
+        y: 0,
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      const normalizeWhitespace = (value) => value.replace(/\s+/g, " ").trim();
+      const clipValue = (value, limit) => value.length <= limit ? value : `${value.slice(0, Math.max(0, limit - 1))}\u2026`;
+      const toTag = (element) => element.tagName.toLowerCase();
+      const isTransparent = (value) => value === "transparent" || value === "rgba(0, 0, 0, 0)" || value === "rgba(0,0,0,0)";
+      const hasVisibleBorder = (style) => Number.parseFloat(style.borderTopWidth) > 0 || Number.parseFloat(style.borderRightWidth) > 0 || Number.parseFloat(style.borderBottomWidth) > 0 || Number.parseFloat(style.borderLeftWidth) > 0;
+      const hasPaintedBox = (style) => style.backgroundImage !== "none" || !isTransparent(style.backgroundColor) || hasVisibleBorder(style) || style.boxShadow !== "none";
+      const escapeIdentifier = (value) => typeof CSS !== "undefined" && typeof CSS.escape === "function" ? CSS.escape(value) : value;
+      const directTextSnippet = (element) => {
+        const text = element instanceof HTMLElement ? element.innerText || element.textContent || "" : element.textContent || "";
+        return clipValue(normalizeWhitespace(text), maxTextLength);
+      };
+      const depthFromRoot = (element) => {
+        let depth = 0;
+        let current = element;
+        while (current && current !== root) {
+          depth += 1;
+          current = current.parentElement;
+        }
+        return depth;
+      };
+      const nthOfType = (element) => {
+        let index = 1;
+        let sibling = element.previousElementSibling;
+        while (sibling) {
+          if (sibling.tagName === element.tagName) {
+            index += 1;
+          }
+          sibling = sibling.previousElementSibling;
+        }
+        return index;
+      };
+      const segmentFor = (element) => {
+        const tag = toTag(element);
+        if (element.id) {
+          return `${tag}#${escapeIdentifier(element.id)}`;
+        }
+        const classNames = Array.from(element.classList).filter((className) => /^[A-Za-z_][\w-]*$/u.test(className)).slice(0, 2);
+        if (classNames.length > 0) {
+          return `${tag}.${classNames.map((className) => escapeIdentifier(className)).join(".")}`;
+        }
+        return `${tag}:nth-of-type(${nthOfType(element)})`;
+      };
+      const buildSelector = (element) => {
+        if (element === root) {
+          return clipValue(segmentFor(element), maxSelectorLength);
+        }
+        const parts = [];
+        let current = element;
+        while (current && parts.length < 3) {
+          parts.unshift(segmentFor(current));
+          if (current === root) {
+            break;
+          }
+          current = current.parentElement;
+        }
+        return clipValue(parts.join(" > "), maxSelectorLength);
+      };
+      const clipBoxToBounds = (box, bounds) => {
+        const left = Math.max(bounds.x, box.x);
+        const top = Math.max(bounds.y, box.y);
+        const right = Math.min(bounds.x + bounds.width, box.x + box.width);
+        const bottom = Math.min(bounds.y + bounds.height, box.y + box.height);
+        if (right <= left || bottom <= top) {
+          return null;
+        }
+        return {
+          x: Math.round(left),
+          y: Math.round(top),
+          width: Math.round(right - left),
+          height: Math.round(bottom - top)
+        };
+      };
+      const clippedEdgesForBox = (box, bounds) => {
+        const edges = [];
+        if (box.y < bounds.y) {
+          edges.push("top");
+        }
+        if (box.x + box.width > bounds.x + bounds.width) {
+          edges.push("right");
+        }
+        if (box.y + box.height > bounds.y + bounds.height) {
+          edges.push("bottom");
+        }
+        if (box.x < bounds.x) {
+          edges.push("left");
+        }
+        return edges;
+      };
+      const toRelativeBox = (element) => {
+        const rect = element.getBoundingClientRect();
+        const x = fullPageCapture ? rect.left + window.scrollX : rect.left;
+        const y = fullPageCapture ? rect.top + window.scrollY : rect.top;
+        const rawBox = {
+          x,
+          y,
+          width: rect.width,
+          height: rect.height
+        };
+        const bbox = clipBoxToBounds(rawBox, captureBounds);
+        if (!bbox) {
+          return null;
+        }
+        return {
+          bbox,
+          captureClippedEdges: clippedEdgesForBox(rawBox, captureBounds)
+        };
+      };
+      const isVisible = (element) => {
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) {
+          return false;
+        }
+        const style = window.getComputedStyle(element);
+        return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0" && style.pointerEvents !== "none";
+      };
+      const isMeaningful = (element) => {
+        if (element === root) {
+          return true;
+        }
+        const tag = toTag(element);
+        if (excludedTags.has(tag) || inlineNoiseTags.has(tag)) {
+          return false;
+        }
+        if (!isVisible(element)) {
+          return false;
+        }
+        const style = window.getComputedStyle(element);
+        const hasText = directTextSnippet(element).length > 0;
+        const hasRole = Boolean(element.getAttribute("role"));
+        return hasText || hasRole || semanticTags.has(tag) || hasPaintedBox(style) || element.children.length === 0;
+      };
+      const buildSnapshotElement = (element) => {
+        const boxInfo = toRelativeBox(element);
+        if (!boxInfo) {
+          return null;
+        }
+        const style = window.getComputedStyle(element);
+        const textMetrics = element instanceof HTMLElement ? {
+          clientWidth: Math.round(element.clientWidth),
+          clientHeight: Math.round(element.clientHeight),
+          scrollWidth: Math.round(element.scrollWidth),
+          scrollHeight: Math.round(element.scrollHeight),
+          overflowX: style.overflowX,
+          overflowY: style.overflowY,
+          textOverflow: style.textOverflow,
+          whiteSpace: style.whiteSpace,
+          lineClamp: style.getPropertyValue("-webkit-line-clamp") || style.getPropertyValue("line-clamp") || null
+        } : null;
+        return {
+          id: buildSelector(element),
+          tag: toTag(element),
+          selector: buildSelector(element),
+          role: element.getAttribute("role"),
+          textSnippet: directTextSnippet(element) || null,
+          bbox: boxInfo.bbox,
+          depth: depthFromRoot(element),
+          captureClippedEdges: boxInfo.captureClippedEdges,
+          textMetrics
+        };
+      };
+      const allElements = [root, ...Array.from(root.querySelectorAll("*"))].filter((element) => isMeaningful(element)).map((element) => buildSnapshotElement(element)).filter((element) => element !== null);
+      const [snapshotRoot, ...elements] = allElements;
+      if (!snapshotRoot) {
+        throw new Error("No meaningful DOM elements were found in the page capture.");
+      }
+      return {
+        root: snapshotRoot,
+        elements
+      };
+    },
+    {
+      fullPageCapture: fullPage,
+      maxSelectorLength: DEFAULT_MAX_SELECTOR_LENGTH,
+      maxTextLength: DEFAULT_MAX_TEXT_SNIPPET_LENGTH
+    }
+  );
+}
+
+// src/compare/engine.ts
+import pixelmatch from "pixelmatch";
+
+// src/compare/regions.ts
+function extractRegions(mask, width, height, minPixels = DEFAULT_MIN_REGION_PIXELS) {
+  const visited = new Uint8Array(mask.length);
+  const regions = [];
+  const queue = new Uint32Array(mask.length);
+  for (let index = 0; index < mask.length; index += 1) {
+    if (mask[index] === 0 || visited[index] === 1) {
+      continue;
+    }
+    let head = 0;
+    let tail = 0;
+    queue[tail] = index;
+    tail += 1;
+    visited[index] = 1;
+    let minX = index % width;
+    let maxX = minX;
+    let minY = Math.floor(index / width);
+    let maxY = minY;
+    let pixelCount = 0;
+    while (head < tail) {
+      const current = queue[head];
+      head += 1;
+      const x = current % width;
+      const y = Math.floor(current / width);
+      pixelCount += 1;
+      minX = Math.min(minX, x);
+      maxX = Math.max(maxX, x);
+      minY = Math.min(minY, y);
+      maxY = Math.max(maxY, y);
+      if (x > 0) {
+        const neighbor = current - 1;
+        if (mask[neighbor] === 1 && visited[neighbor] === 0) {
+          visited[neighbor] = 1;
+          queue[tail] = neighbor;
+          tail += 1;
+        }
+      }
+      if (x < width - 1) {
+        const neighbor = current + 1;
+        if (mask[neighbor] === 1 && visited[neighbor] === 0) {
+          visited[neighbor] = 1;
+          queue[tail] = neighbor;
+          tail += 1;
+        }
+      }
+      if (y > 0) {
+        const neighbor = current - width;
+        if (mask[neighbor] === 1 && visited[neighbor] === 0) {
+          visited[neighbor] = 1;
+          queue[tail] = neighbor;
+          tail += 1;
+        }
+      }
+      if (y < height - 1) {
+        const neighbor = current + width;
+        if (mask[neighbor] === 1 && visited[neighbor] === 0) {
+          visited[neighbor] = 1;
+          queue[tail] = neighbor;
+          tail += 1;
+        }
+      }
+    }
+    if (pixelCount < minPixels) {
+      continue;
+    }
+    regions.push({
+      x: minX,
+      y: minY,
+      width: maxX - minX + 1,
+      height: maxY - minY + 1,
+      pixelCount
+    });
+  }
+  return regions;
+}
+
+// src/compare/structure.ts
+function analyzeStructure(reference, preview, width, height) {
+  const lumaReference = rgbaToLuma(reference, width, height);
+  const lumaPreview = rgbaToLuma(preview, width, height);
+  const edgeMaskReference = sobelEdgeMask(lumaReference, width, height, DEFAULT_EDGE_THRESHOLD);
+  const edgeMaskPreview = sobelEdgeMask(lumaPreview, width, height, DEFAULT_EDGE_THRESHOLD);
+  const edgeDiffMask = new Uint8Array(width * height);
+  let unionCount = 0;
+  let diffCount = 0;
+  for (let index = 0; index < edgeDiffMask.length; index += 1) {
+    const ref = edgeMaskReference[index];
+    const prev = edgeMaskPreview[index];
+    const union = ref === 1 || prev === 1;
+    if (union) {
+      unionCount += 1;
+    }
+    if (ref !== prev) {
+      edgeDiffMask[index] = 1;
+      diffCount += 1;
+    }
+  }
+  return {
+    edgeMaskReference,
+    edgeMaskPreview,
+    edgeDiffMask,
+    structuralMismatchPercent: unionCount === 0 ? 0 : diffCount / unionCount * 100
+  };
+}
+function rgbaToLuma(data, width, height) {
+  const luma = new Float32Array(width * height);
+  for (let index = 0; index < width * height; index += 1) {
+    const offset = index * 4;
+    luma[index] = data[offset] * 0.2126 + data[offset + 1] * 0.7152 + data[offset + 2] * 0.0722;
+  }
+  return luma;
+}
+function sobelEdgeMask(luma, width, height, threshold) {
+  const edgeMask = new Uint8Array(width * height);
+  for (let y = 1; y < height - 1; y += 1) {
+    for (let x = 1; x < width - 1; x += 1) {
+      const topLeft = luma[(y - 1) * width + (x - 1)];
+      const top = luma[(y - 1) * width + x];
+      const topRight = luma[(y - 1) * width + (x + 1)];
+      const left = luma[y * width + (x - 1)];
+      const right = luma[y * width + (x + 1)];
+      const bottomLeft = luma[(y + 1) * width + (x - 1)];
+      const bottom = luma[(y + 1) * width + x];
+      const bottomRight = luma[(y + 1) * width + (x + 1)];
+      const gx = -topLeft + topRight - 2 * left + 2 * right - bottomLeft + bottomRight;
+      const gy = topLeft + 2 * top + topRight - bottomLeft - 2 * bottom - bottomRight;
+      const magnitude = Math.sqrt(gx * gx + gy * gy);
+      if (magnitude >= threshold) {
+        edgeMask[y * width + x] = 1;
+      }
+    }
+  }
+  return edgeMask;
+}
+
+// src/compare/engine.ts
+function runComparisonEngine(params) {
+  const totalPixels = params.width * params.height;
+  const diffBuffer = new Uint8ClampedArray(totalPixels * 4);
+  const maskBuffer = new Uint8ClampedArray(totalPixels * 4);
+  const colorDeltaMap = new Float32Array(totalPixels);
+  const mismatchPixels = pixelmatch(
+    params.reference,
+    params.preview,
+    diffBuffer,
+    params.width,
+    params.height,
+    {
+      threshold: DEFAULT_PIXELMATCH_THRESHOLD,
+      alpha: 0.2,
+      diffColor: [255, 0, 0],
+      diffColorAlt: [0, 180, 255],
+      includeAA: true
+    }
+  );
+  pixelmatch(params.reference, params.preview, maskBuffer, params.width, params.height, {
+    threshold: DEFAULT_PIXELMATCH_THRESHOLD,
+    alpha: 1,
+    diffColor: [255, 255, 255],
+    diffColorAlt: [255, 255, 255],
+    includeAA: true,
+    diffMask: true
+  });
+  const mismatchMask = new Uint8Array(totalPixels);
+  let colorDeltaSum = 0;
+  let maxColorDelta = 0;
+  let mismatchedColorSamples = 0;
+  for (let index = 0; index < totalPixels; index += 1) {
+    const offset = index * 4;
+    const hasMismatch = maskBuffer[offset] > 0 || maskBuffer[offset + 1] > 0 || maskBuffer[offset + 2] > 0 || maskBuffer[offset + 3] > 0;
+    if (!hasMismatch) {
+      continue;
+    }
+    mismatchMask[index] = 1;
+    const redDelta = params.reference[offset] - params.preview[offset];
+    const greenDelta = params.reference[offset + 1] - params.preview[offset + 1];
+    const blueDelta = params.reference[offset + 2] - params.preview[offset + 2];
+    const delta = Math.sqrt(redDelta ** 2 + greenDelta ** 2 + blueDelta ** 2) / MAX_RGB_DISTANCE * 100;
+    colorDeltaMap[index] = delta;
+    colorDeltaSum += delta;
+    maxColorDelta = Math.max(maxColorDelta, delta);
+    mismatchedColorSamples += 1;
+  }
+  const dimensionMismatch = buildDimensionMismatch(
+    params.referenceOriginal,
+    params.previewOriginal
+  );
+  const structural = params.mode === "all" || params.mode === "layout" ? analyzeStructure(params.reference, params.preview, params.width, params.height) : null;
+  const rawRegions = buildRegions({
+    mismatchMask,
+    edgeDiffMask: structural?.edgeDiffMask ?? null,
+    width: params.width,
+    height: params.height,
+    totalPixels,
+    dimensionMismatch,
+    overlapWidth: Math.min(params.referenceOriginal.width, params.previewOriginal.width),
+    overlapHeight: Math.min(params.referenceOriginal.height, params.previewOriginal.height),
+    colorDeltaMap,
+    mode: params.mode
+  });
+  const overlay = createOverlay(params.reference, params.preview, mismatchMask);
+  return {
+    metrics: {
+      mismatchPixels,
+      mismatchPercent: totalPixels === 0 ? 0 : Number((mismatchPixels / totalPixels * 100).toFixed(4)),
+      meanColorDelta: params.mode === "all" || params.mode === "color" ? mismatchedColorSamples > 0 ? Number((colorDeltaSum / mismatchedColorSamples).toFixed(4)) : 0 : null,
+      maxColorDelta: params.mode === "all" || params.mode === "color" ? Number(maxColorDelta.toFixed(4)) : null,
+      structuralMismatchPercent: structural === null ? null : Number(structural.structuralMismatchPercent.toFixed(4)),
+      dimensionMismatch,
+      findingsCount: 0,
+      affectedElementCount: 0
+    },
+    rawRegions,
+    mismatchMask,
+    buffers: {
+      overlay,
+      diff: diffBuffer
+    }
+  };
+}
+function buildDimensionMismatch(reference, preview) {
+  const widthDelta = preview.width - reference.width;
+  const heightDelta = preview.height - reference.height;
+  const referenceAspect = reference.width / reference.height;
+  const previewAspect = preview.width / preview.height;
+  return {
+    widthDelta,
+    heightDelta,
+    aspectRatioDelta: Number(Math.abs(previewAspect - referenceAspect).toFixed(6)),
+    hasMismatch: widthDelta !== 0 || heightDelta !== 0
+  };
+}
+function buildRegions(params) {
+  const rawRegions = extractRegions(params.mismatchMask, params.width, params.height);
+  return rawRegions.map((region) => {
+    const bboxArea = region.width * region.height;
+    const mismatchPercent = bboxArea === 0 ? 0 : region.pixelCount / bboxArea * 100;
+    const kind = classifyRegionKind({
+      region,
+      edgeDiffMask: params.edgeDiffMask,
+      width: params.width,
+      overlapWidth: params.overlapWidth,
+      overlapHeight: params.overlapHeight,
+      colorDeltaMap: params.colorDeltaMap,
+      mode: params.mode
+    });
+    const severity = classifyRegionSeverity(
+      region.pixelCount / params.totalPixels * 100,
+      kind,
+      params.dimensionMismatch
+    );
+    return {
+      ...region,
+      mismatchPercent: Number(mismatchPercent.toFixed(4)),
+      kind,
+      severity
+    };
+  }).sort(compareRegions);
+}
+function classifyRegionKind(params) {
+  const { region, edgeDiffMask, width, overlapWidth, overlapHeight, colorDeltaMap, mode } = params;
+  const outsideOverlap = region.x + region.width > overlapWidth || region.y + region.height > overlapHeight;
+  if (outsideOverlap) {
+    return "dimension";
+  }
+  const regionMeanColorDelta = meanColorDeltaForRegion(region, colorDeltaMap, width);
+  if (mode === "pixel") {
+    return "pixel";
+  }
+  if (mode === "color") {
+    return regionMeanColorDelta >= COLOR_REGION_DELTA_THRESHOLD ? "color" : "pixel";
+  }
+  if (!edgeDiffMask) {
+    return regionMeanColorDelta >= COLOR_REGION_DELTA_THRESHOLD ? "color" : "pixel";
+  }
+  let edgePixels = 0;
+  for (let y = region.y; y < region.y + region.height; y += 1) {
+    for (let x = region.x; x < region.x + region.width; x += 1) {
+      if (edgeDiffMask[y * width + x] === 1) {
+        edgePixels += 1;
+      }
+    }
+  }
+  const edgeRatio = edgePixels / Math.max(1, region.width * region.height);
+  if (mode === "layout") {
+    return edgeRatio >= LAYOUT_EDGE_RATIO_THRESHOLD ? "layout" : "pixel";
+  }
+  if (edgeRatio >= LAYOUT_EDGE_RATIO_THRESHOLD && regionMeanColorDelta >= COLOR_REGION_DELTA_THRESHOLD) {
+    return "mixed";
+  }
+  if (edgeRatio >= LAYOUT_EDGE_RATIO_THRESHOLD) {
+    return "layout";
+  }
+  if (regionMeanColorDelta >= COLOR_REGION_DELTA_THRESHOLD) {
+    return "color";
+  }
+  return "pixel";
+}
+function meanColorDeltaForRegion(region, colorDeltaMap, width) {
+  let totalDelta = 0;
+  let sampleCount = 0;
+  for (let y = region.y; y < region.y + region.height; y += 1) {
+    for (let x = region.x; x < region.x + region.width; x += 1) {
+      const delta = colorDeltaMap[y * width + x];
+      if (delta <= 0) {
+        continue;
+      }
+      totalDelta += delta;
+      sampleCount += 1;
+    }
+  }
+  return sampleCount === 0 ? 0 : totalDelta / sampleCount;
+}
+function classifyRegionSeverity(areaPercent, kind, dimensionMismatch) {
+  if (kind === "dimension") {
+    const strongDimensionShift = Math.abs(dimensionMismatch.widthDelta) >= STRONG_DIMENSION_DELTA_PX || Math.abs(dimensionMismatch.heightDelta) >= STRONG_DIMENSION_DELTA_PX || dimensionMismatch.aspectRatioDelta >= STRONG_DIMENSION_ASPECT_DELTA;
+    return strongDimensionShift ? "critical" : "high";
+  }
+  let severity;
+  if (areaPercent >= 12) {
+    severity = "critical";
+  } else if (areaPercent >= 4) {
+    severity = "high";
+  } else if (areaPercent >= 1.5) {
+    severity = "medium";
+  } else {
+    severity = "low";
+  }
+  if (kind === "layout" && severity === "low") {
+    return "medium";
+  }
+  if (kind === "mixed" && severity === "low") {
+    return "medium";
+  }
+  return severity;
+}
+function createOverlay(reference, preview, mismatchMask) {
+  const overlay = new Uint8ClampedArray(reference.length);
+  for (let index = 0; index < mismatchMask.length; index += 1) {
+    const offset = index * 4;
+    overlay[offset] = Math.round((reference[offset] + preview[offset]) / 2);
+    overlay[offset + 1] = Math.round((reference[offset + 1] + preview[offset + 1]) / 2);
+    overlay[offset + 2] = Math.round((reference[offset + 2] + preview[offset + 2]) / 2);
+    overlay[offset + 3] = 255;
+    if (mismatchMask[index] === 1) {
+      overlay[offset] = Math.min(255, overlay[offset] + 50);
+    }
+  }
+  return overlay;
+}
+function compareRegions(left, right) {
+  const severityOrder = compareSeverityDescending(left.severity, right.severity);
+  if (severityOrder !== 0) {
+    return severityOrder;
+  }
+  if (left.pixelCount !== right.pixelCount) {
+    return right.pixelCount - left.pixelCount;
+  }
+  if (left.y !== right.y) {
+    return left.y - right.y;
+  }
+  return left.x - right.x;
+}
+
+// src/compare/heatmap.ts
+function createHeatmapArtifact(params) {
+  const heatmap = new Uint8ClampedArray(params.reference.length);
+  for (let index = 0; index < params.mismatchMask.length; index += 1) {
+    const offset = index * 4;
+    const base = Math.round((params.reference[offset] + params.preview[offset]) / 2 * 0.25);
+    heatmap[offset] = base;
+    heatmap[offset + 1] = base;
+    heatmap[offset + 2] = base;
+    heatmap[offset + 3] = 255;
+    if (params.mismatchMask[index] === 1) {
+      heatmap[offset] = 255;
+      heatmap[offset + 1] = 120;
+      heatmap[offset + 2] = 0;
+    }
+  }
+  for (const visual of params.visuals) {
+    drawBoundingBox(
+      heatmap,
+      params.width,
+      params.height,
+      visual.primaryBox,
+      boundingBoxColor(visual.severity),
+      2
+    );
+    for (const hotspotBox of visual.hotspotBoxes) {
+      drawBoundingBox(
+        heatmap,
+        params.width,
+        params.height,
+        hotspotBox,
+        hotspotColor(visual.severity),
+        1
+      );
+    }
+  }
+  return heatmap;
+}
+function drawBoundingBox(image, width, height, box, color, thickness) {
+  for (let inset = 0; inset < thickness; inset += 1) {
+    const xStart = Math.max(0, box.x + inset);
+    const yStart = Math.max(0, box.y + inset);
+    const xEnd = Math.min(width - 1, box.x + box.width - 1 - inset);
+    const yEnd = Math.min(height - 1, box.y + box.height - 1 - inset);
+    if (xEnd < xStart || yEnd < yStart) {
+      continue;
+    }
+    for (let x = xStart; x <= xEnd; x += 1) {
+      paintPixel(image, width, x, yStart, color);
+      paintPixel(image, width, x, yEnd, color);
+    }
+    for (let y = yStart; y <= yEnd; y += 1) {
+      paintPixel(image, width, xStart, y, color);
+      paintPixel(image, width, xEnd, y, color);
+    }
+  }
+}
+function paintPixel(image, width, x, y, color) {
+  const offset = (y * width + x) * 4;
+  image[offset] = color[0];
+  image[offset + 1] = color[1];
+  image[offset + 2] = color[2];
+  image[offset + 3] = color[3];
+}
+function boundingBoxColor(severity) {
+  switch (severity) {
+    case "critical":
+      return [255, 255, 255, 255];
+    case "high":
+      return [255, 0, 255, 255];
+    case "medium":
+      return [0, 255, 255, 255];
+    case "low":
+    default:
+      return [0, 255, 0, 255];
+  }
+}
+function hotspotColor(severity) {
+  switch (severity) {
+    case "critical":
+      return [255, 220, 120, 255];
+    case "high":
+      return [255, 140, 120, 255];
+    case "medium":
+      return [120, 220, 255, 255];
+    case "low":
+    default:
+      return [120, 255, 180, 255];
+  }
+}
+
+// src/io/fs.ts
+import { access, mkdir, stat, writeFile as writeFile2 } from "fs/promises";
+import path3 from "path";
+async function ensureDirectory(dirPath) {
+  const resolved = path3.resolve(dirPath);
+  await mkdir(resolved, { recursive: true });
+  return resolved;
+}
+async function ensureFileExists(filePath) {
+  const resolved = path3.resolve(filePath);
+  try {
+    const fileStat = await stat(resolved);
+    if (!fileStat.isFile()) {
+      throw new AppError(`Expected a file but received a different path: ${resolved}`);
+    }
+    return resolved;
+  } catch (error) {
+    if (error instanceof AppError) {
+      throw error;
+    }
+    const code = error.code;
+    if (code === "ENOENT") {
+      throw new AppError(`Input file does not exist: ${resolved}`, {
+        code: "input_file_missing",
+        cause: error
+      });
+    }
+    if (code === "EACCES") {
+      throw new AppError(`Input file is not readable: ${resolved}`, {
+        code: "input_file_unreadable",
+        cause: error
+      });
+    }
+    throw new AppError(`Failed to access input file: ${resolved}`, {
+      code: "input_file_access_failed",
+      cause: error
+    });
+  }
+}
+async function writeJsonFile(filePath, value) {
+  await writeFile2(filePath, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/io/inputs.ts
+import path4 from "path";
+
+// src/utils/url.ts
+function parseUrl(value) {
+  try {
+    return new URL(value);
+  } catch {
+    return null;
+  }
+}
+function isHttpUrl(value) {
+  const url = parseUrl(value);
+  return url?.protocol === "http:" || url?.protocol === "https:";
+}
+function isFigmaUrl(value) {
+  const url = parseUrl(value);
+  if (!url) {
+    return false;
+  }
+  return url.hostname === "figma.com" || url.hostname.endsWith(".figma.com");
+}
+function hashToSelector(input, explicitSelector) {
+  if (explicitSelector) {
+    return explicitSelector;
+  }
+  if (!isHttpUrl(input)) {
+    return null;
+  }
+  const url = new URL(input);
+  const hash = url.hash.replace(/^#/, "");
+  if (!hash) {
+    return null;
+  }
+  return `#${decodeURIComponent(hash)}`;
+}
+function normalizeNodeId(value) {
+  return decodeURIComponent(value).replace(/-/g, ":");
+}
+function parseFigmaUrl(input) {
+  const url = parseUrl(input);
+  if (!url) {
+    throw new AppError(`Invalid Figma URL: ${input}`, {
+      code: "figma_url_invalid"
+    });
+  }
+  if (!isFigmaUrl(input)) {
+    throw new AppError(`Reference URL must be a Figma URL or local image path: ${input}`, {
+      code: "figma_url_expected"
+    });
+  }
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    throw new AppError(`Could not extract file key from Figma URL: ${input}`, {
+      code: "figma_file_key_missing"
+    });
+  }
+  let fileKey;
+  if (parts[0] === "design" && parts[2] === "branch") {
+    fileKey = parts[3];
+  } else if (parts[0] === "design" || parts[0] === "file") {
+    fileKey = parts[1];
+  } else if (parts[1] === "branch" && parts[2]) {
+    fileKey = parts[2];
+  }
+  if (!fileKey) {
+    fileKey = parts[1];
+  }
+  const nodeId = url.searchParams.get("node-id");
+  if (!nodeId) {
+    throw new AppError(
+      `Figma URL must include a node-id query parameter so the CLI can export the correct frame: ${input}`,
+      {
+        exitCode: 3,
+        recommendation: "needs_human_review",
+        severity: "high",
+        code: "figma_node_id_missing"
+      }
+    );
+  }
+  return {
+    fileKey,
+    nodeId: normalizeNodeId(nodeId),
+    resolved: url.toString()
+  };
+}
+
+// src/utils/viewport.ts
+function parseViewport(value) {
+  const trimmedValue = value.trim();
+  const explicitMatch = /^(?<width>\d+)x(?<height>\d+)$/i.exec(trimmedValue);
+  if (explicitMatch?.groups) {
+    const width = Number(explicitMatch.groups.width);
+    const height = Number(explicitMatch.groups.height);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+      throw new AppError(
+        `Invalid viewport "${value}". Width and height must be positive integers.`,
+        {
+          code: "viewport_invalid_dimensions"
+        }
+      );
+    }
+    return { width, height };
+  }
+  const widthOnlyMatch = /^(?<width>\d+)$/i.exec(trimmedValue);
+  if (widthOnlyMatch?.groups) {
+    const width = Number(widthOnlyMatch.groups.width);
+    if (!Number.isFinite(width) || width <= 0) {
+      throw new AppError(`Invalid viewport "${value}". Width must be a positive integer.`, {
+        code: "viewport_invalid_width"
+      });
+    }
+    return {
+      width,
+      height: DEFAULT_VIEWPORT_HEIGHT
+    };
+  }
+  throw new AppError(
+    `Invalid viewport "${value}". Expected WIDTH or WIDTHxHEIGHT, for example 1920 or 1920x900.`,
+    {
+      code: "viewport_invalid_format"
+    }
+  );
+}
+
+// src/io/inputs.ts
+async function parsePreviewInput(options) {
+  const selector = hashToSelector(options.preview, options.selector);
+  if (isHttpUrl(options.preview)) {
+    if (!options.viewport) {
+      throw new AppError(
+        "Preview URL requires --viewport so the browser screenshot is deterministic.",
+        {
+          code: "preview_viewport_required"
+        }
+      );
+    }
+    const viewport2 = parseViewport(options.viewport);
+    if (options.fullPage && selector) {
+      throw new AppError(
+        "--full-page cannot be used together with --selector or a preview URL hash fragment.",
+        {
+          code: "preview_full_page_selector_conflict"
+        }
+      );
+    }
+    return {
+      kind: "url",
+      input: options.preview,
+      resolved: new URL(options.preview).toString(),
+      selector,
+      viewport: viewport2
+    };
+  }
+  if (options.selector) {
+    throw new AppError("--selector can only be used when --preview is a URL.", {
+      code: "preview_selector_requires_url"
+    });
+  }
+  if (options.fullPage) {
+    throw new AppError("--full-page can only be used when --preview is a URL.", {
+      code: "preview_full_page_requires_url"
+    });
+  }
+  const resolvedPath = await ensureFileExists(options.preview);
+  const viewport = options.viewport ? parseViewport(options.viewport) : null;
+  return {
+    kind: "path",
+    input: options.preview,
+    resolved: resolvedPath,
+    selector: null,
+    viewport
+  };
+}
+async function parseReferenceInput(reference) {
+  if (isHttpUrl(reference)) {
+    const parsedFigmaUrl = parseFigmaUrl(reference);
+    return {
+      kind: "figma-url",
+      input: reference,
+      resolved: parsedFigmaUrl.resolved,
+      fileKey: parsedFigmaUrl.fileKey,
+      nodeId: parsedFigmaUrl.nodeId
+    };
+  }
+  const resolvedPath = await ensureFileExists(reference);
+  return {
+    kind: "path",
+    input: reference,
+    resolved: resolvedPath
+  };
+}
+function resolveViewportForReport(previewViewport, imageDimensions) {
+  return previewViewport ?? { width: imageDimensions.width, height: imageDimensions.height };
+}
+function inferPreviewInputSource(options) {
+  if (isHttpUrl(options.preview)) {
+    return {
+      input: options.preview,
+      kind: "url",
+      resolved: new URL(options.preview).toString(),
+      selector: hashToSelector(options.preview, options.selector)
+    };
+  }
+  return {
+    input: options.preview,
+    kind: "path",
+    resolved: path4.resolve(options.preview),
+    selector: null
+  };
+}
+function inferReferenceInputSource(reference) {
+  if (isHttpUrl(reference)) {
+    return {
+      input: reference,
+      kind: isFigmaUrl(reference) ? "figma-url" : "url",
+      resolved: new URL(reference).toString(),
+      selector: null,
+      transport: null
+    };
+  }
+  return {
+    input: reference,
+    kind: "path",
+    resolved: path4.resolve(reference),
+    selector: null,
+    transport: "path"
+  };
+}
+
+// src/reference/figma-mcp-reference-provider.ts
+import { spawn } from "child_process";
+import { createHash } from "crypto";
+import { createServer } from "http";
+import { readFile, rm, writeFile as writeFile3 } from "fs/promises";
+import os from "os";
+import path5 from "path";
+import sharp2 from "sharp";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  StreamableHTTPClientTransport,
+  StreamableHTTPError
+} from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+var PEYE_CLIENT_NAME = "peye";
+var PEYE_CLIENT_VERSION = "0.1.0";
+var SCREENSHOT_TOOL_NAME = "get_screenshot";
+var METADATA_TOOL_NAME = "get_metadata";
+var MAX_ACCEPTABLE_ASPECT_RATIO_DELTA = 0.02;
+var FigmaMcpReferenceProvider = class {
+  kind = "figma-url";
+  serverUrl;
+  transport;
+  constructor(options) {
+    this.serverUrl = options.serverUrl;
+    this.transport = options.transport;
+  }
+  async prepare(reference, outputPath) {
+    if (reference.kind !== "figma-url") {
+      throw new AppError(
+        `Unsupported reference input kind for Figma MCP provider: ${reference.kind}`,
+        {
+          code: "reference_provider_kind_mismatch"
+        }
+      );
+    }
+    const callbackServer = this.transport === "figma-mcp-remote" && isInteractiveTerminal() ? await createOAuthCallbackServer() : null;
+    const oauthProvider = this.transport === "figma-mcp-remote" && callbackServer ? await PersistentOAuthClientProvider.create(this.serverUrl, callbackServer) : null;
+    const transportOptions = oauthProvider === null ? { fetch: fetchWithTimeout } : { authProvider: oauthProvider, fetch: fetchWithTimeout };
+    const transport = new StreamableHTTPClientTransport(new URL(this.serverUrl), transportOptions);
+    const client = new Client(
+      {
+        name: PEYE_CLIENT_NAME,
+        version: PEYE_CLIENT_VERSION
+      },
+      {
+        capabilities: {}
+      }
+    );
+    try {
+      await runWithOAuthRetry(
+        transport,
+        oauthProvider,
+        callbackServer,
+        () => client.connect(transport)
+      );
+      const tools = await runWithOAuthRetry(
+        transport,
+        oauthProvider,
+        callbackServer,
+        () => client.listTools()
+      );
+      const hasScreenshotTool = tools.tools.some((tool) => tool.name === SCREENSHOT_TOOL_NAME);
+      if (!hasScreenshotTool) {
+        throw new AppError(
+          `Figma MCP server at ${this.serverUrl} does not expose ${SCREENSHOT_TOOL_NAME}.`,
+          {
+            code: "figma_mcp_tool_missing"
+          }
+        );
+      }
+      const result = await runWithOAuthRetry(
+        transport,
+        oauthProvider,
+        callbackServer,
+        () => client.callTool({
+          name: SCREENSHOT_TOOL_NAME,
+          arguments: {
+            fileKey: reference.fileKey,
+            nodeId: reference.nodeId
+          }
+        })
+      );
+      const buffer = extractImageBuffer(result, this.serverUrl);
+      const resizeTarget = tools.tools.some((tool) => tool.name === METADATA_TOOL_NAME) ? await resolveMetadataResizeTarget(
+        client,
+        transport,
+        oauthProvider,
+        callbackServer,
+        reference,
+        buffer
+      ) : null;
+      const prepared = resizeTarget === null ? await bufferToNormalizedPng(buffer, outputPath) : await bufferToNormalizedPng(buffer, outputPath, {
+        resizeTo: resizeTarget
+      });
+      return {
+        ...prepared,
+        transport: this.transport
+      };
+    } catch (error) {
+      throw mapMcpError(error, this.transport, this.serverUrl);
+    } finally {
+      await client.close().catch(() => void 0);
+      await transport.close().catch(() => void 0);
+      await callbackServer?.close().catch(() => void 0);
+    }
+  }
+};
+async function resolveMetadataResizeTarget(client, transport, oauthProvider, callbackServer, reference, screenshotBuffer) {
+  const metadataResult = await runWithOAuthRetry(
+    transport,
+    oauthProvider,
+    callbackServer,
+    () => client.callTool({
+      name: METADATA_TOOL_NAME,
+      arguments: {
+        fileKey: reference.fileKey,
+        nodeId: reference.nodeId
+      }
+    })
+  );
+  const targetDimensions = extractNodeDimensions(metadataResult);
+  if (targetDimensions === null) {
+    return null;
+  }
+  const currentDimensions = await readBufferDimensions(screenshotBuffer);
+  if (currentDimensions.width >= targetDimensions.width || currentDimensions.height >= targetDimensions.height) {
+    return null;
+  }
+  const currentAspectRatio = currentDimensions.width / currentDimensions.height;
+  const targetAspectRatio = targetDimensions.width / targetDimensions.height;
+  if (Math.abs(currentAspectRatio - targetAspectRatio) > MAX_ACCEPTABLE_ASPECT_RATIO_DELTA) {
+    return null;
+  }
+  return targetDimensions;
+}
+async function runWithOAuthRetry(transport, provider, callbackServer, operation) {
+  let hasRetried = false;
+  while (true) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (!(error instanceof UnauthorizedError) || provider === null || callbackServer === null) {
+        throw error;
+      }
+      if (hasRetried) {
+        throw error;
+      }
+      hasRetried = true;
+      const authorizationCode = await callbackServer.waitForAuthorizationCode();
+      await transport.finishAuth(authorizationCode);
+    }
+  }
+}
+function extractImageBuffer(result, serverUrl) {
+  if ("toolResult" in result) {
+    throw new AppError(`Figma MCP server at ${serverUrl} returned an unsupported tool result.`, {
+      exitCode: 3,
+      recommendation: "needs_human_review",
+      severity: "high",
+      code: "figma_mcp_invalid_response"
+    });
+  }
+  if (result.isError) {
+    const message = extractTextContent(result.content) ?? "Figma MCP tool returned an error.";
+    throw new AppError(message, {
+      exitCode: 3,
+      recommendation: "needs_human_review",
+      severity: "high",
+      code: "figma_mcp_invalid_response"
+    });
+  }
+  for (const block of result.content) {
+    if (block.type === "image" && block.mimeType.startsWith("image/")) {
+      return Buffer.from(block.data, "base64");
+    }
+    if (block.type === "resource" && "blob" in block.resource) {
+      const mimeType = block.resource.mimeType ?? "";
+      if (mimeType.startsWith("image/")) {
+        return Buffer.from(block.resource.blob, "base64");
+      }
+    }
+  }
+  throw new AppError(
+    `Figma MCP server at ${serverUrl} returned no image content for get_screenshot.`,
+    {
+      exitCode: 3,
+      recommendation: "needs_human_review",
+      severity: "high",
+      code: "figma_mcp_invalid_response"
+    }
+  );
+}
+function extractNodeDimensions(result) {
+  if ("toolResult" in result || result.isError) {
+    return null;
+  }
+  const metadataText = extractTextContent(result.content);
+  if (!metadataText) {
+    return null;
+  }
+  const rootTagMatch = metadataText.match(/<[^>]+>/);
+  if (!rootTagMatch) {
+    return null;
+  }
+  const widthMatch = rootTagMatch[0].match(/\bwidth="([^"]+)"/);
+  const heightMatch = rootTagMatch[0].match(/\bheight="([^"]+)"/);
+  const width = Math.round(Number.parseFloat(widthMatch?.[1] ?? ""));
+  const height = Math.round(Number.parseFloat(heightMatch?.[1] ?? ""));
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    return null;
+  }
+  return { width, height };
+}
+function extractTextContent(content) {
+  for (const block of content) {
+    if (block.type === "text") {
+      return block.text ?? null;
+    }
+  }
+  return null;
+}
+async function readBufferDimensions(buffer) {
+  const metadata = await sharp2(buffer).metadata();
+  if (!metadata.width || !metadata.height) {
+    throw new AppError("Could not read dimensions from the Figma MCP screenshot buffer.", {
+      code: "figma_mcp_invalid_response"
+    });
+  }
+  return {
+    width: metadata.width,
+    height: metadata.height
+  };
+}
+function mapMcpError(error, transport, serverUrl) {
+  if (error instanceof AppError) {
+    return error;
+  }
+  if (error instanceof UnauthorizedError) {
+    return new AppError(
+      transport === "figma-mcp-remote" ? "Remote Figma MCP requires OAuth authorization." : `Figma MCP at ${serverUrl} rejected the request as unauthorized.`,
+      {
+        code: "figma_mcp_auth_required",
+        cause: error
+      }
+    );
+  }
+  if (error instanceof StreamableHTTPError && error.code === 401) {
+    return new AppError(
+      transport === "figma-mcp-remote" ? "Remote Figma MCP requires OAuth authorization." : `Figma MCP at ${serverUrl} rejected the request as unauthorized.`,
+      {
+        code: "figma_mcp_auth_required",
+        cause: error
+      }
+    );
+  }
+  return new AppError(
+    `Failed to read Figma reference through ${transport} at ${serverUrl}. ${ensureError(error).message}`,
+    {
+      code: "figma_mcp_request_failed",
+      cause: error
+    }
+  );
+}
+function isInteractiveTerminal() {
+  return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+function fetchWithTimeout(input, init) {
+  const timeoutSignal = AbortSignal.timeout(DEFAULT_RESOURCE_TIMEOUT_MS);
+  const signal = init?.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
+  return fetch(input, {
+    ...init,
+    signal
+  });
+}
+var PersistentOAuthClientProvider = class _PersistentOAuthClientProvider {
+  callbackServer;
+  storagePath;
+  oauthState;
+  constructor(callbackServer, storagePath, state) {
+    this.callbackServer = callbackServer;
+    this.storagePath = storagePath;
+    this.oauthState = state;
+  }
+  static async create(serverUrl, callbackServer) {
+    const storagePath = await oauthStatePath(serverUrl);
+    const state = await loadOAuthState(storagePath);
+    return new _PersistentOAuthClientProvider(callbackServer, storagePath, state);
+  }
+  get redirectUrl() {
+    return this.callbackServer.redirectUrl;
+  }
+  get clientMetadata() {
+    return {
+      client_name: "peye",
+      redirect_uris: [this.callbackServer.redirectUrl],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none"
+    };
+  }
+  clientInformation() {
+    return this.oauthState.clientInformation;
+  }
+  async saveClientInformation(clientInformation) {
+    this.oauthState.clientInformation = clientInformation;
+    await this.persist();
+  }
+  tokens() {
+    return this.oauthState.tokens;
+  }
+  async saveTokens(tokens) {
+    this.oauthState.tokens = tokens;
+    await this.persist();
+  }
+  redirectToAuthorization(authorizationUrl) {
+    process.stderr.write(
+      [
+        "Remote Figma MCP requires authorization.",
+        `Open this URL to continue: ${authorizationUrl.toString()}`
+      ].join("\n") + "\n"
+    );
+    openExternalUrl(authorizationUrl.toString());
+  }
+  async saveCodeVerifier(codeVerifier) {
+    this.oauthState.codeVerifier = codeVerifier;
+    await this.persist();
+  }
+  codeVerifier() {
+    if (!this.oauthState.codeVerifier) {
+      throw new Error("No OAuth code verifier available.");
+    }
+    return this.oauthState.codeVerifier;
+  }
+  async invalidateCredentials(scope) {
+    if (scope === "all" || scope === "client") {
+      delete this.oauthState.clientInformation;
+    }
+    if (scope === "all" || scope === "tokens") {
+      delete this.oauthState.tokens;
+    }
+    if (scope === "all" || scope === "verifier") {
+      delete this.oauthState.codeVerifier;
+    }
+    if (scope === "all" || scope === "discovery") {
+      delete this.oauthState.discoveryState;
+    }
+    const hasState = Object.values(this.oauthState).some((value) => value !== void 0);
+    if (!hasState) {
+      await rm(this.storagePath, { force: true }).catch(() => void 0);
+      return;
+    }
+    await this.persist();
+  }
+  discoveryState() {
+    return this.oauthState.discoveryState;
+  }
+  async saveDiscoveryState(state) {
+    this.oauthState.discoveryState = state;
+    await this.persist();
+  }
+  async persist() {
+    await ensureDirectory(path5.dirname(this.storagePath));
+    await writeFile3(this.storagePath, `${JSON.stringify(this.oauthState, null, 2)}
+`, "utf8");
+  }
+};
+async function loadOAuthState(storagePath) {
+  try {
+    const raw = await readFile(storagePath, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    const message = ensureError(error).message;
+    if (error.code === "ENOENT") {
+      return {};
+    }
+    throw new AppError(`Failed to load persisted Figma MCP OAuth state. ${message}`, {
+      code: "figma_mcp_oauth_state_invalid",
+      cause: error
+    });
+  }
+}
+async function oauthStatePath(serverUrl) {
+  const digest = createHash("sha256").update(serverUrl).digest("hex").slice(0, 16);
+  const dir = path5.join(resolveConfigDir(), "oauth");
+  await ensureDirectory(dir);
+  return path5.join(dir, `figma-${digest}.json`);
+}
+function resolveConfigDir() {
+  if (process.platform === "win32" && process.env.APPDATA) {
+    return path5.join(process.env.APPDATA, "peye");
+  }
+  if (process.env.XDG_CONFIG_HOME) {
+    return path5.join(process.env.XDG_CONFIG_HOME, "peye");
+  }
+  return path5.join(os.homedir(), ".config", "peye");
+}
+async function createOAuthCallbackServer() {
+  const deferred = createDeferred();
+  const server = createServer((request, response) => {
+    const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+    const authorizationCode = requestUrl.searchParams.get("code");
+    const error = requestUrl.searchParams.get("error");
+    if (authorizationCode) {
+      response.statusCode = 200;
+      response.setHeader("content-type", "text/html; charset=utf-8");
+      response.end(
+        "<html><body><h1>Authorization complete</h1><p>You can close this window.</p></body></html>"
+      );
+      deferred.resolve(authorizationCode);
+      return;
+    }
+    if (error) {
+      response.statusCode = 400;
+      response.setHeader("content-type", "text/html; charset=utf-8");
+      response.end(`<html><body><h1>Authorization failed</h1><p>${error}</p></body></html>`);
+      deferred.reject(new Error(`OAuth authorization failed: ${error}`));
+      return;
+    }
+    response.statusCode = 400;
+    response.setHeader("content-type", "text/html; charset=utf-8");
+    response.end("<html><body><h1>Invalid callback</h1></body></html>");
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new AppError("Failed to start local OAuth callback server.", {
+      code: "figma_mcp_oauth_callback_failed"
+    });
+  }
+  return {
+    redirectUrl: `http://127.0.0.1:${address.port}/callback`,
+    waitForAuthorizationCode: async () => {
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          reject(
+            new AppError("Timed out waiting for the Figma MCP OAuth callback.", {
+              code: "figma_mcp_oauth_timeout"
+            })
+          );
+        }, DEFAULT_FIGMA_OAUTH_TIMEOUT_MS);
+        timeout.unref?.();
+        deferred.promise.then(
+          (code) => {
+            clearTimeout(timeout);
+            resolve(code);
+          },
+          (error) => {
+            clearTimeout(timeout);
+            reject(ensureError(error));
+          }
+        );
+      });
+    },
+    close: async () => {
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    }
+  };
+}
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((innerResolve, innerReject) => {
+    resolve = innerResolve;
+    reject = innerReject;
+  });
+  return {
+    promise,
+    reject,
+    resolve
+  };
+}
+function openExternalUrl(url) {
+  const command = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
+  const [file, ...args] = command;
+  try {
+    const child = spawn(file, args, {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.once("error", () => {
+      process.stderr.write("Open the authorization URL manually if the browser did not start.\n");
+    });
+    child.unref();
+  } catch {
+    process.stderr.write(`Open the authorization URL manually if the browser did not start.
+`);
+  }
+}
+
+// src/reference/figma-rest-reference-provider.ts
+var FigmaRestReferenceProvider = class {
+  kind = "figma-url";
+  async prepare(reference, outputPath) {
+    if (reference.kind !== "figma-url") {
+      throw new AppError(`Unsupported reference input kind for Figma provider: ${reference.kind}`, {
+        code: "reference_provider_kind_mismatch"
+      });
+    }
+    const token = process.env.FIGMA_TOKEN;
+    if (!token) {
+      throw new AppError("FIGMA_TOKEN is required when --reference points to a Figma URL.", {
+        code: "figma_token_missing"
+      });
+    }
+    const endpoint = new URL(`/v1/images/${reference.fileKey}`, figmaApiBaseUrl());
+    endpoint.searchParams.set("ids", reference.nodeId);
+    endpoint.searchParams.set("format", "png");
+    endpoint.searchParams.set("scale", "1");
+    const payload = await fetchFigmaJson(
+      endpoint,
+      token,
+      `Failed to export Figma node image for ${reference.nodeId}.`
+    );
+    const imageUrl = payload.images?.[reference.nodeId];
+    if (!imageUrl) {
+      throw new AppError(`Figma did not return an image URL for node ${reference.nodeId}.`, {
+        exitCode: 3,
+        recommendation: "needs_human_review",
+        severity: "high",
+        code: "figma_image_missing"
+      });
+    }
+    const buffer = await fetchBinary(
+      imageUrl,
+      `Failed to download exported Figma image for ${reference.nodeId}.`
+    );
+    const prepared = await bufferToNormalizedPng(buffer, outputPath);
+    return {
+      ...prepared,
+      transport: "figma-rest"
+    };
+  }
+};
+function figmaApiBaseUrl() {
+  return process.env.FIGMA_API_BASE_URL ?? DEFAULT_FIGMA_API_BASE_URL;
+}
+async function fetchFigmaJson(url, token, failureMessage) {
+  const response = await fetchWithTimeout2(
+    url,
+    {
+      headers: {
+        "X-Figma-Token": token
+      }
+    },
+    failureMessage
+  );
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new AppError(`${failureMessage} Invalid JSON response from Figma API.`, {
+      code: "figma_response_invalid_json",
+      cause: error
+    });
+  }
+}
+async function fetchBinary(url, failureMessage) {
+  const response = await fetchWithTimeout2(url, void 0, failureMessage);
+  return Buffer.from(await response.arrayBuffer());
+}
+async function fetchWithTimeout2(input, init, failureMessage) {
+  try {
+    const response = await fetch(input, {
+      ...init,
+      signal: AbortSignal.timeout(DEFAULT_RESOURCE_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      throw new AppError(`${failureMessage} Received ${response.status} ${response.statusText}.`, {
+        code: "remote_request_failed"
+      });
+    }
+    return response;
+  } catch (error) {
+    if (error instanceof AppError) {
+      throw error;
+    }
+    throw new AppError(`${failureMessage} ${ensureError(error).message}`, {
+      code: "remote_request_failed",
+      cause: error
+    });
+  }
+}
+
+// src/reference/figma-reference-provider.ts
+var FigmaReferenceProvider = class {
+  kind = "figma-url";
+  async prepare(reference, outputPath) {
+    const providers2 = buildProviders();
+    const failures = [];
+    for (const provider of providers2) {
+      try {
+        return await provider.instance.prepare(reference, outputPath);
+      } catch (error) {
+        const appError = error instanceof AppError ? error : new AppError(ensureError(error).message, {
+          cause: error,
+          code: "figma_reference_attempt_failed"
+        });
+        failures.push({
+          label: provider.label,
+          error: appError
+        });
+      }
+    }
+    throw buildFailureFromAttempts(failures);
+  }
+};
+function buildProviders() {
+  const mode = resolveFigmaSourceMode();
+  const desktopProvider = new FigmaMcpReferenceProvider({
+    serverUrl: process.env.PEYE_FIGMA_MCP_DESKTOP_URL ?? DEFAULT_FIGMA_MCP_DESKTOP_URL,
+    transport: "figma-mcp-desktop"
+  });
+  const remoteProvider = new FigmaMcpReferenceProvider({
+    serverUrl: process.env.PEYE_FIGMA_MCP_REMOTE_URL ?? DEFAULT_FIGMA_MCP_REMOTE_URL,
+    transport: "figma-mcp-remote"
+  });
+  const restProvider = new FigmaRestReferenceProvider();
+  if (mode === "rest") {
+    return [{ instance: restProvider, label: "Figma REST" }];
+  }
+  if (mode === "mcp") {
+    return [
+      { instance: desktopProvider, label: "Figma MCP desktop" },
+      { instance: remoteProvider, label: "Figma MCP remote" }
+    ];
+  }
+  return [
+    { instance: desktopProvider, label: "Figma MCP desktop" },
+    { instance: remoteProvider, label: "Figma MCP remote" },
+    { instance: restProvider, label: "Figma REST" }
+  ];
+}
+function resolveFigmaSourceMode() {
+  const mode = process.env.PEYE_FIGMA_SOURCE ?? DEFAULT_FIGMA_SOURCE;
+  if (mode === "auto" || mode === "mcp" || mode === "rest") {
+    return mode;
+  }
+  throw new AppError(
+    `Invalid PEYE_FIGMA_SOURCE value "${mode}". Expected one of: auto, mcp, rest.`,
+    {
+      code: "figma_source_invalid"
+    }
+  );
+}
+function buildFailureFromAttempts(failures) {
+  if (failures.length === 1) {
+    return failures[0].error;
+  }
+  const preferredError = failures.find(
+    (failure) => failure.error.code === "figma_mcp_invalid_response" || failure.error.code === "figma_image_missing"
+  )?.error ?? failures.at(-1)?.error;
+  const nextSteps = [
+    "Start the Figma desktop app MCP server.",
+    "Run peye in an interactive terminal to authorize remote Figma MCP.",
+    "Set FIGMA_TOKEN to enable REST fallback."
+  ];
+  const attemptLines = failures.map((failure) => `- ${failure.label}: ${failure.error.message}`);
+  return new AppError(
+    [
+      preferredError?.message ?? "Failed to resolve the Figma reference.",
+      "Reference lookup attempts:",
+      ...attemptLines,
+      "Next steps:",
+      ...nextSteps.map((step) => `- ${step}`)
+    ].join("\n"),
+    {
+      exitCode: preferredError?.exitCode ?? 3,
+      recommendation: preferredError?.recommendation ?? "needs_human_review",
+      severity: preferredError?.severity ?? "high",
+      code: preferredError?.code ?? "figma_reference_unavailable",
+      cause: preferredError
+    }
+  );
+}
+
+// src/reference/local-reference-provider.ts
+var LocalReferenceProvider = class {
+  kind = "path";
+  async prepare(reference, outputPath) {
+    try {
+      const prepared = await normalizeImageToPng(reference.resolved, outputPath);
+      return {
+        ...prepared,
+        transport: "path"
+      };
+    } catch (error) {
+      throw new AppError(
+        `Failed to normalize reference image: ${reference.resolved}. ${ensureError(error).message}`,
+        {
+          code: "reference_image_normalization_failed",
+          cause: error
+        }
+      );
+    }
+  }
+};
+
+// src/reference/index.ts
+var providers = /* @__PURE__ */ new Map([
+  ["figma-url", new FigmaReferenceProvider()],
+  ["path", new LocalReferenceProvider()]
+]);
+async function materializeReferenceImage(reference, outputPath) {
+  const provider = providers.get(reference.kind);
+  if (!provider) {
+    throw new AppError(`No reference provider registered for ${reference.kind}.`, {
+      code: "reference_provider_missing"
+    });
+  }
+  return provider.prepare(reference, outputPath);
+}
+
+// src/core/run-compare.ts
+async function runCompare(options) {
+  validateThresholdOrdering(options);
+  const outputDir = await ensureDirectory(options.output);
+  const artifactPaths = createArtifactPaths(outputDir);
+  let previewInput = null;
+  let referenceInput = null;
+  let preparedPreview = null;
+  let preparedReference = null;
+  try {
+    previewInput = await parsePreviewInput(options);
+    referenceInput = await parseReferenceInput(options.reference);
+    preparedPreview = await materializePreviewImage(
+      previewInput,
+      artifactPaths.preview,
+      options.fullPage
+    );
+    preparedReference = await materializeReferenceImage(referenceInput, artifactPaths.reference);
+    const previewImage = await loadNormalizedImage(preparedPreview.path);
+    const referenceImage = await loadNormalizedImage(preparedReference.path);
+    const width = Math.max(previewImage.width, referenceImage.width);
+    const height = Math.max(previewImage.height, referenceImage.height);
+    const paddedPreview = padImageToCanvas(previewImage, width, height);
+    const paddedReference = padImageToCanvas(referenceImage, width, height);
+    const comparison = runComparisonEngine({
+      reference: paddedReference.data,
+      preview: paddedPreview.data,
+      width,
+      height,
+      referenceOriginal: {
+        width: referenceImage.width,
+        height: referenceImage.height
+      },
+      previewOriginal: {
+        width: previewImage.width,
+        height: previewImage.height
+      },
+      mode: options.mode ?? DEFAULT_MODE
+    });
+    const findingsAnalysis = buildFindingsAnalysis({
+      analysisMode: preparedPreview.analysisMode,
+      rawRegions: comparison.rawRegions,
+      domSnapshot: preparedPreview.domSnapshot,
+      width,
+      height
+    });
+    const heatmap = createHeatmapArtifact({
+      reference: paddedReference.data,
+      preview: paddedPreview.data,
+      mismatchMask: comparison.mismatchMask,
+      visuals: findingsAnalysis.visuals,
+      width,
+      height
+    });
+    await Promise.all([
+      writeRawRgbaPng(artifactPaths.overlay, comparison.buffers.overlay, width, height),
+      writeRawRgbaPng(artifactPaths.diff, comparison.buffers.diff, width, height),
+      writeRawRgbaPng(artifactPaths.heatmap, heatmap, width, height)
+    ]);
+    const metrics = {
+      ...comparison.metrics,
+      findingsCount: findingsAnalysis.metrics.findingsCount,
+      affectedElementCount: findingsAnalysis.metrics.affectedElementCount
+    };
+    const decision = decideRecommendation({
+      metrics,
+      thresholds: {
+        pass: options.thresholdPass,
+        tolerated: options.thresholdTolerated,
+        retry: options.thresholdRetry
+      },
+      findings: findingsAnalysis.findings
+    });
+    const report = {
+      analysisMode: preparedPreview.analysisMode,
+      summary: decision,
+      inputs: {
+        preview: {
+          input: previewInput.input,
+          kind: previewInput.kind,
+          resolved: previewInput.resolved,
+          selector: previewInput.selector
+        },
+        reference: {
+          input: referenceInput.input,
+          kind: referenceInput.kind,
+          resolved: referenceInput.resolved,
+          selector: null,
+          transport: preparedReference.transport
+        },
+        viewport: resolveViewportForReport(previewInput.viewport, {
+          width: previewImage.width,
+          height: previewImage.height
+        }),
+        mode: options.mode,
+        fullPage: options.fullPage
+      },
+      images: {
+        preview: { width: previewImage.width, height: previewImage.height },
+        reference: { width: referenceImage.width, height: referenceImage.height },
+        canvas: { width, height }
+      },
+      metrics,
+      rollups: findingsAnalysis.rollups,
+      findings: findingsAnalysis.findings,
+      artifacts: artifactPaths,
+      error: null
+    };
+    await writeJsonFile(artifactPaths.report, report);
+    return {
+      report,
+      exitCode: exitCodeForRecommendation(report.summary.recommendation)
+    };
+  } catch (error) {
+    if (isAppError(error)) {
+      const report = createFailureReport({
+        reason: error.message,
+        recommendation: error.recommendation ?? "needs_human_review",
+        severity: error.severity ?? (error.exitCode === 1 ? "medium" : "high"),
+        preview: toPreviewSourceReport(previewInput, options),
+        reference: toReferenceSourceReport(referenceInput, options.reference, preparedReference),
+        viewport: previewInput?.viewport ?? null,
+        analysisMode: preparedPreview?.analysisMode ?? inferAnalysisMode(previewInput, options),
+        mode: options.mode,
+        fullPage: options.fullPage,
+        images: buildImagesReport(preparedPreview, preparedReference),
+        artifacts: {
+          ...artifactPaths,
+          preview: await pathExists(artifactPaths.preview) ? artifactPaths.preview : null,
+          reference: await pathExists(artifactPaths.reference) ? artifactPaths.reference : null,
+          overlay: null,
+          diff: null,
+          heatmap: null
+        },
+        error: {
+          code: error.code,
+          message: error.message,
+          exitCode: error.exitCode
+        }
+      });
+      await writeJsonFile(artifactPaths.report, report);
+      return {
+        report,
+        exitCode: error.exitCode
+      };
+    }
+    throw error;
+  }
+}
+function buildImagesReport(preparedPreview, preparedReference) {
+  const preview = preparedPreview === null ? null : {
+    width: preparedPreview.width,
+    height: preparedPreview.height
+  };
+  const reference = preparedReference === null ? null : {
+    width: preparedReference.width,
+    height: preparedReference.height
+  };
+  return {
+    preview,
+    reference,
+    canvas: preview === null || reference === null ? null : {
+      width: Math.max(preview.width, reference.width),
+      height: Math.max(preview.height, reference.height)
+    }
+  };
+}
+function inferAnalysisMode(previewInput, options) {
+  if (previewInput) {
+    return previewInput.kind === "url" ? "dom-elements" : "visual-clusters";
+  }
+  return options.preview.startsWith("http://") || options.preview.startsWith("https://") ? "dom-elements" : "visual-clusters";
+}
+function createArtifactPaths(outputDir) {
+  return {
+    preview: path6.join(outputDir, "preview.png"),
+    reference: path6.join(outputDir, "reference.png"),
+    overlay: path6.join(outputDir, "overlay.png"),
+    diff: path6.join(outputDir, "diff.png"),
+    heatmap: path6.join(outputDir, "heatmap.png"),
+    report: path6.join(outputDir, "report.json")
+  };
+}
+function toPreviewSourceReport(previewInput, options) {
+  if (!previewInput) {
+    return inferPreviewInputSource(options);
+  }
+  return {
+    input: previewInput.input,
+    kind: previewInput.kind,
+    resolved: previewInput.resolved,
+    selector: previewInput.selector
+  };
+}
+function toReferenceSourceReport(referenceInput, reference, preparedReference) {
+  if (preparedReference) {
+    const inferred = inferReferenceInputSource(reference);
+    return {
+      input: referenceInput?.input ?? reference,
+      kind: referenceInput?.kind ?? inferred.kind,
+      resolved: referenceInput?.resolved ?? inferred.resolved,
+      selector: null,
+      transport: preparedReference.transport
+    };
+  }
+  if (!referenceInput) {
+    return inferReferenceInputSource(reference);
+  }
+  return {
+    input: referenceInput.input,
+    kind: referenceInput.kind,
+    resolved: referenceInput.resolved,
+    selector: null,
+    transport: referenceInput.kind === "path" ? "path" : null
+  };
+}
+function validateThresholdOrdering(options) {
+  if (options.thresholdPass > options.thresholdTolerated) {
+    throw new AppError("--threshold-pass must be less than or equal to --threshold-tolerated.");
+  }
+  if (options.thresholdTolerated > options.thresholdRetry) {
+    throw new AppError("--threshold-tolerated must be less than or equal to --threshold-retry.");
+  }
+}
+function exitCodeForRecommendation(recommendation) {
+  switch (recommendation) {
+    case "pass":
+    case "pass_with_tolerated_differences":
+      return 0;
+    case "retry_fix":
+      return 2;
+    case "needs_human_review":
+      return 3;
+    default:
+      return 1;
+  }
+}
+
+// src/types/report.ts
+var COMPARE_MODES = ["all", "pixel", "layout", "color"];
+
+// src/cli/compare-command.ts
+function registerCompareCommand(program2) {
+  program2.command("compare").description("Compare a preview screenshot or URL against a Figma reference or local image.").requiredOption("--preview <url|path>", "Preview URL or screenshot path").requiredOption("--reference <figma-url|path>", "Figma URL or local reference screenshot path").requiredOption("--output <dir>", "Output directory for report and generated artifacts").option(
+    "--viewport <width|widthxheight>",
+    "Viewport width or widthxheight used for preview URL capture, for example 1920 or 1920x900"
+  ).option("--mode <mode>", "Analysis mode: all, pixel, layout, color", DEFAULT_MODE).option("--selector <css>", "CSS selector for preview element capture").option("--full-page", "Capture the full preview page when preview is a URL", false).option("--quiet", "Suppress the human-readable terminal summary", false).option(
+    "--report-stdout",
+    "Write compact report JSON to stdout and suppress the human-readable summary",
+    false
+  ).option(
+    "--threshold-pass <number>",
+    "Pass threshold in percent",
+    parseFloat,
+    DEFAULT_THRESHOLDS.pass
+  ).option(
+    "--threshold-tolerated <number>",
+    "Tolerated threshold in percent",
+    parseFloat,
+    DEFAULT_THRESHOLDS.tolerated
+  ).option(
+    "--threshold-retry <number>",
+    "Retry threshold in percent",
+    parseFloat,
+    DEFAULT_THRESHOLDS.retry
+  ).action(async (rawOptions) => {
+    const { quiet, reportStdout, ...options } = validateOptions(rawOptions);
+    const result = await runCompare(options);
+    writeCliOutput(result.report, { quiet, reportStdout });
+    process.exitCode = result.exitCode;
+  });
+}
+function validateOptions(options) {
+  if (!COMPARE_MODES.includes(options.mode)) {
+    throw new AppError(
+      `Invalid --mode value "${options.mode}". Expected one of: ${COMPARE_MODES.join(", ")}.`
+    );
+  }
+  for (const [label, value] of [
+    ["threshold-pass", options.thresholdPass],
+    ["threshold-tolerated", options.thresholdTolerated],
+    ["threshold-retry", options.thresholdRetry]
+  ]) {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new AppError(`--${label} must be a non-negative number.`);
+    }
+  }
+  return options;
+}
+function writeCliOutput(report, options) {
+  if (options.reportStdout) {
+    process.stdout.write(`${JSON.stringify(report)}
+`);
+    return;
+  }
+  if (options.quiet) {
+    return;
+  }
+  printSummary(report);
+}
+function printSummary(report) {
+  console.log(`recommendation: ${report.summary.recommendation}`);
+  console.log(`severity: ${report.summary.severity}`);
+  console.log(`reason: ${report.summary.reason}`);
+  console.log(`mismatchPercent: ${report.metrics.mismatchPercent.toFixed(4)}%`);
+  console.log(`findings: ${report.findings.length}/${report.metrics.findingsCount}`);
+  console.log(`output: ${path7.dirname(report.artifacts.report)}`);
+}
+function handleCliError(error) {
+  if (isAppError(error)) {
+    console.error(error.message);
+    process.exitCode = error.exitCode;
+    return;
+  }
+  if (error instanceof Error) {
+    console.error(error.message);
+  } else {
+    console.error("Unknown error");
+  }
+  process.exitCode = 1;
+}
+
+// src/cli/bin.ts
+var program = new Command();
+program.name("peye").version(package_default.version).description(
+  "Standalone visual diff CLI for comparing preview screenshots against Figma references."
+).configureHelp({
+  sortOptions: true,
+  sortSubcommands: true
+}).showHelpAfterError();
+registerCompareCommand(program);
+program.parseAsync(process.argv).catch(handleCliError);
+//# sourceMappingURL=bin.js.map