devlens-mcp 0.3.0

package/src/visual/layout-analyzer.ts

@@ -0,0 +1,283 @@
+import pixelmatch from "pixelmatch";
+import type { RefEntry } from "../snapshot/ref-registry.js";
+
+/**
+ * Layout-aware comparison engine.
+ *
+ * Uses the accessibility tree (via RefRegistry) to identify semantic UI regions,
+ * scales those regions from device coordinate space into Figma image space,
+ * and compares each region independently via pixelmatch.
+ *
+ * This gives per-element similarity scores ("Header: 92%, ChatInput: 44%")
+ * instead of a single misleading global pixel-diff percentage.
+ */
+
+export interface RegionComparisonResult {
+  ref: string;
+  elementType: string;
+  text?: string;
+  label?: string;
+  /** Element bounds in device pixel space */
+  deviceBounds: { left: number; top: number; width: number; height: number };
+  /** Corresponding bounds in Figma image space (after scaling) */
+  figmaBounds: { left: number; top: number; width: number; height: number };
+  similarity: number;
+  diffPixels: number;
+  totalPixels: number;
+  verdict: "excellent" | "good" | "partial" | "poor";
+}
+
+export interface LayoutReport {
+  regions: RegionComparisonResult[];
+  /** Weighted average similarity across all analyzed regions */
+  overallSimilarity: number;
+  /** Number of refs skipped (too small, out of bounds, crop failed) */
+  skippedRefs: number;
+  deviceDimensions: { width: number; height: number };
+  figmaDimensions: { width: number; height: number };
+}
+
+/** Minimum element area (px²) for inclusion in layout analysis */
+const MIN_REGION_AREA = 3000;
+
+/** Color difference threshold for pixelmatch (matches global comparator default) */
+const REGION_THRESHOLD = 0.1;
+
+function verdictFromSimilarity(s: number): RegionComparisonResult["verdict"] {
+  if (s >= 0.92) return "excellent";
+  if (s >= 0.80) return "good";
+  if (s >= 0.60) return "partial";
+  return "poor";
+}
+
+/** Scale device-space element bounds into Figma image pixel space */
+function scaleToFigmaSpace(
+  bounds: { x: number; y: number; width: number; height: number },
+  deviceW: number,
+  deviceH: number,
+  figmaW: number,
+  figmaH: number
+): { left: number; top: number; width: number; height: number } {
+  const scaleX = figmaW / deviceW;
+  const scaleY = figmaH / deviceH;
+  return {
+    left: Math.round(bounds.x * scaleX),
+    top: Math.round(bounds.y * scaleY),
+    width: Math.max(1, Math.round(bounds.width * scaleX)),
+    height: Math.max(1, Math.round(bounds.height * scaleY)),
+  };
+}
+
+/** Clamp bounds to image dimensions. Returns null if there's no overlap. */
+function clampBounds(
+  b: { left: number; top: number; width: number; height: number },
+  maxW: number,
+  maxH: number
+): { left: number; top: number; width: number; height: number } | null {
+  const left = Math.max(0, b.left);
+  const top = Math.max(0, b.top);
+  const right = Math.min(maxW, b.left + b.width);
+  const bottom = Math.min(maxH, b.top + b.height);
+  if (right <= left || bottom <= top) return null;
+  return { left, top, width: right - left, height: bottom - top };
+}
+
+/**
+ * Crop a PNG buffer to a region and return raw RGBA bytes + dimensions.
+ * Uses sharp's raw() output so pixelmatch can consume it directly
+ * without a PNG encode/decode round-trip.
+ */
+async function cropToRaw(
+  imageBuffer: Buffer,
+  bounds: { left: number; top: number; width: number; height: number }
+): Promise<{ data: Buffer; width: number; height: number } | null> {
+  try {
+    const sharp = (await import("sharp")).default;
+    const result = await sharp(imageBuffer)
+      .extract({ left: bounds.left, top: bounds.top, width: bounds.width, height: bounds.height })
+      .ensureAlpha()
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+    return { data: result.data, width: result.info.width, height: result.info.height };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resize raw RGBA bytes to target dimensions.
+ * Used to match device crop and Figma crop pixel dimensions before pixelmatch.
+ */
+async function resizeRaw(
+  raw: { data: Buffer; width: number; height: number },
+  targetW: number,
+  targetH: number
+): Promise<{ data: Buffer; width: number; height: number } | null> {
+  if (raw.width === targetW && raw.height === targetH) return raw;
+  try {
+    const sharp = (await import("sharp")).default;
+    const result = await sharp(raw.data, {
+      raw: { width: raw.width, height: raw.height, channels: 4 },
+    })
+      .resize(targetW, targetH, { fit: "fill" })
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+    return { data: result.data, width: result.info.width, height: result.info.height };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Core function: for each ref with sufficient area, scale its device bounds
+ * into Figma image space, crop both images, and compare independently.
+ *
+ * @param deviceBuffer   Full-screen device screenshot PNG
+ * @param figmaBuffer    Preprocessed Figma image PNG (artifacts already removed)
+ * @param refs           All RefEntry objects from RefRegistry.getAllRefs()
+ * @param deviceW        Device screen width in pixels
+ * @param deviceH        Device screen height in pixels
+ */
+export async function buildLayoutReport(
+  deviceBuffer: Buffer,
+  figmaBuffer: Buffer,
+  refs: RefEntry[],
+  deviceW: number,
+  deviceH: number
+): Promise<LayoutReport> {
+  const sharp = (await import("sharp")).default;
+
+  const figmaMeta = await sharp(figmaBuffer).metadata();
+  const figmaW = figmaMeta.width!;
+  const figmaH = figmaMeta.height!;
+
+  const regions: RegionComparisonResult[] = [];
+  let skippedRefs = 0;
+
+  for (const entry of refs) {
+    const { bounds } = entry;
+    const area = bounds.width * bounds.height;
+
+    if (area < MIN_REGION_AREA) {
+      skippedRefs++;
+      continue;
+    }
+
+    const deviceBounds = { left: bounds.x, top: bounds.y, width: bounds.width, height: bounds.height };
+    const figmaBounds = scaleToFigmaSpace(bounds, deviceW, deviceH, figmaW, figmaH);
+
+    const clampedDevice = clampBounds(deviceBounds, deviceW, deviceH);
+    const clampedFigma = clampBounds(figmaBounds, figmaW, figmaH);
+
+    if (!clampedDevice || !clampedFigma) {
+      skippedRefs++;
+      continue;
+    }
+
+    // Crop both in parallel
+    const [deviceCrop, figmaCrop] = await Promise.all([
+      cropToRaw(deviceBuffer, clampedDevice),
+      cropToRaw(figmaBuffer, clampedFigma),
+    ]);
+
+    if (!deviceCrop || !figmaCrop) {
+      skippedRefs++;
+      continue;
+    }
+
+    // Resize Figma crop to exactly match device crop dimensions
+    const figmaResized = await resizeRaw(figmaCrop, deviceCrop.width, deviceCrop.height);
+    if (!figmaResized) {
+      skippedRefs++;
+      continue;
+    }
+
+    const totalPixels = deviceCrop.width * deviceCrop.height;
+    const diff = Buffer.alloc(totalPixels * 4);
+
+    const diffPixels = pixelmatch(
+      deviceCrop.data,
+      figmaResized.data,
+      diff,
+      deviceCrop.width,
+      deviceCrop.height,
+      { threshold: REGION_THRESHOLD, includeAA: false }
+    );
+
+    const similarity = 1 - diffPixels / totalPixels;
+
+    regions.push({
+      ref: entry.ref,
+      elementType: entry.node.type,
+      text: entry.node.text,
+      label: entry.node.label,
+      deviceBounds,
+      figmaBounds,
+      similarity,
+      diffPixels,
+      totalPixels,
+      verdict: verdictFromSimilarity(similarity),
+    });
+  }
+
+  // Weighted average by region area
+  const totalWeight = regions.reduce((s, r) => s + r.totalPixels, 0);
+  const overallSimilarity = totalWeight > 0
+    ? regions.reduce((s, r) => s + r.similarity * r.totalPixels, 0) / totalWeight
+    : 0;
+
+  return {
+    regions,
+    overallSimilarity,
+    skippedRefs,
+    deviceDimensions: { width: deviceW, height: deviceH },
+    figmaDimensions: { width: figmaW, height: figmaH },
+  };
+}
+
+/** Format layout report as human-readable text for MCP tool output */
+export function formatLayoutReport(report: LayoutReport): string {
+  const scaleX = (report.deviceDimensions.width / report.figmaDimensions.width).toFixed(2);
+  const scaleY = (report.deviceDimensions.height / report.figmaDimensions.height).toFixed(2);
+
+  const lines: string[] = [
+    "--- Layout Region Analysis ---",
+    `Device: ${report.deviceDimensions.width}x${report.deviceDimensions.height}px`,
+    `Figma:  ${report.figmaDimensions.width}x${report.figmaDimensions.height}px`,
+    `Scale:  ${scaleX}x (horizontal) ${scaleY}x (vertical)`,
+    `Regions: ${report.regions.length} analyzed, ${report.skippedRefs} too small to compare`,
+    "",
+  ];
+
+  if (report.regions.length === 0) {
+    lines.push("No regions to analyze. Run devlens_snapshot first to populate element refs.");
+    return lines.join("\n");
+  }
+
+  // Sort ascending by similarity — problem areas at the bottom
+  const sorted = [...report.regions].sort((a, b) => a.similarity - b.similarity);
+
+  for (const r of sorted) {
+    const icon = r.verdict === "excellent" ? "✓"
+               : r.verdict === "good"      ? "~"
+               : r.verdict === "partial"   ? "!"
+               :                             "X";
+    const pct = (r.similarity * 100).toFixed(1);
+    const label = r.text
+      ? `"${r.text.slice(0, 35)}"`
+      : r.label
+      ? `label="${r.label.slice(0, 35)}"`
+      : r.elementType;
+
+    const suffix = (r.verdict === "poor" || r.verdict === "partial")
+      ? `  <- investigate (${r.diffPixels.toLocaleString()} diff pixels)`
+      : "";
+
+    lines.push(`  [${icon}] [${r.ref}] ${label}: ${pct}%${suffix}`);
+  }
+
+  lines.push("");
+  lines.push(`Overall (area-weighted): ${(report.overallSimilarity * 100).toFixed(1)}%`);
+
+  return lines.join("\n");
+}

package/src/visual/screenshot.ts

@@ -0,0 +1,49 @@
+import { writeFile } from "fs/promises";
+import type { Device } from "../platform/device.js";
+import type { Bounds } from "../platform/device.js";
+
+/**
+ * Screenshot utilities — capture, encode, crop, and save screenshots.
+ */
+
+/** Take a screenshot and return it as base64-encoded PNG */
+export async function captureScreenshot(device: Device): Promise<{
+  buffer: Buffer;
+  base64: string;
+}> {
+  const buffer = await device.takeScreenshot();
+  const base64 = buffer.toString("base64");
+  return { buffer, base64 };
+}
+
+/** Save a screenshot buffer to disk */
+export async function saveScreenshot(
+  buffer: Buffer,
+  filePath: string
+): Promise<void> {
+  await writeFile(filePath, buffer);
+}
+
+/** Crop a screenshot to a specific element's bounds */
+export async function cropToElement(
+  screenshotBuffer: Buffer,
+  bounds: Bounds
+): Promise<Buffer> {
+  const sharp = (await import("sharp")).default;
+
+  return sharp(screenshotBuffer)
+    .extract({
+      left: Math.max(0, Math.round(bounds.x)),
+      top: Math.max(0, Math.round(bounds.y)),
+      width: Math.max(1, Math.round(bounds.width)),
+      height: Math.max(1, Math.round(bounds.height)),
+    })
+    .png()
+    .toBuffer();
+}
+
+/** Generate a default screenshot filename with timestamp */
+export function defaultScreenshotPath(): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return `/tmp/devlens-screenshot-${timestamp}.png`;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*", "bin/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}