devlens-mcp 0.3.0

package/dist/src/visual/layout-analyzer.d.ts

@@ -0,0 +1,64 @@
+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;
+    };
+}
+/**
+ * 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 declare function buildLayoutReport(deviceBuffer: Buffer, figmaBuffer: Buffer, refs: RefEntry[], deviceW: number, deviceH: number): Promise<LayoutReport>;
+/** Format layout report as human-readable text for MCP tool output */
+export declare function formatLayoutReport(report: LayoutReport): string;
+//# sourceMappingURL=layout-analyzer.d.ts.map

package/dist/src/visual/layout-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-analyzer.d.ts","sourceRoot":"","sources":["../../../src/visual/layout-analyzer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D;;;;;;;;;GASG;AAEH,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,gEAAgE;IAChE,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;CACpD;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,eAAe,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AA6FD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,QAAQ,EAAE,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC,CAyFvB;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA4C/D"}

package/dist/src/visual/layout-analyzer.js

@@ -0,0 +1,198 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLayoutReport = buildLayoutReport;
+exports.formatLayoutReport = formatLayoutReport;
+const pixelmatch_1 = __importDefault(require("pixelmatch"));
+/** 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) {
+    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, deviceW, deviceH, figmaW, figmaH) {
+    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, maxW, maxH) {
+    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, bounds) {
+    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, targetW, targetH) {
+    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
+ */
+async function buildLayoutReport(deviceBuffer, figmaBuffer, refs, deviceW, deviceH) {
+    const sharp = (await import("sharp")).default;
+    const figmaMeta = await sharp(figmaBuffer).metadata();
+    const figmaW = figmaMeta.width;
+    const figmaH = figmaMeta.height;
+    const regions = [];
+    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 = (0, pixelmatch_1.default)(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 */
+function formatLayoutReport(report) {
+    const scaleX = (report.deviceDimensions.width / report.figmaDimensions.width).toFixed(2);
+    const scaleY = (report.deviceDimensions.height / report.figmaDimensions.height).toFixed(2);
+    const lines = [
+        "--- 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");
+}
+//# sourceMappingURL=layout-analyzer.js.map

package/dist/src/visual/layout-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-analyzer.js","sourceRoot":"","sources":["../../../src/visual/layout-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/src/visual/screenshot.d.ts

@@ -0,0 +1,17 @@
+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 declare function captureScreenshot(device: Device): Promise<{
+    buffer: Buffer;
+    base64: string;
+}>;
+/** Save a screenshot buffer to disk */
+export declare function saveScreenshot(buffer: Buffer, filePath: string): Promise<void>;
+/** Crop a screenshot to a specific element's bounds */
+export declare function cropToElement(screenshotBuffer: Buffer, bounds: Bounds): Promise<Buffer>;
+/** Generate a default screenshot filename with timestamp */
+export declare function defaultScreenshotPath(): string;
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/src/visual/screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../../src/visual/screenshot.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;GAEG;AAEH,4DAA4D;AAC5D,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAID;AAED,uCAAuC;AACvC,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,uDAAuD;AACvD,wBAAsB,aAAa,CACjC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,IAAI,MAAM,CAG9C"}

package/dist/src/visual/screenshot.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureScreenshot = captureScreenshot;
+exports.saveScreenshot = saveScreenshot;
+exports.cropToElement = cropToElement;
+exports.defaultScreenshotPath = defaultScreenshotPath;
+const promises_1 = require("fs/promises");
+/**
+ * Screenshot utilities — capture, encode, crop, and save screenshots.
+ */
+/** Take a screenshot and return it as base64-encoded PNG */
+async function captureScreenshot(device) {
+    const buffer = await device.takeScreenshot();
+    const base64 = buffer.toString("base64");
+    return { buffer, base64 };
+}
+/** Save a screenshot buffer to disk */
+async function saveScreenshot(buffer, filePath) {
+    await (0, promises_1.writeFile)(filePath, buffer);
+}
+/** Crop a screenshot to a specific element's bounds */
+async function cropToElement(screenshotBuffer, bounds) {
+    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 */
+function defaultScreenshotPath() {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `/tmp/devlens-screenshot-${timestamp}.png`;
+}
+//# sourceMappingURL=screenshot.js.map

package/dist/src/visual/screenshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../../../src/visual/screenshot.ts"],"names":[],"mappings":";;AASA,8CAOC;AAGD,wCAKC;AAGD,sCAeC;AAGD,sDAGC;AAhDD,0CAAwC;AAIxC;;GAEG;AAEH,4DAA4D;AACrD,KAAK,UAAU,iBAAiB,CAAC,MAAc;IAIpD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,EAAE,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC;AAED,uCAAuC;AAChC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,QAAgB;IAEhB,MAAM,IAAA,oBAAS,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,uDAAuD;AAChD,KAAK,UAAU,aAAa,CACjC,gBAAwB,EACxB,MAAc;IAEd,MAAM,KAAK,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAE9C,OAAO,KAAK,CAAC,gBAAgB,CAAC;SAC3B,OAAO,CAAC;QACP,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACtC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;KAC/C,CAAC;SACD,GAAG,EAAE;SACL,QAAQ,EAAE,CAAC;AAChB,CAAC;AAED,4DAA4D;AAC5D,SAAgB,qBAAqB;IACnC,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACjE,OAAO,2BAA2B,SAAS,MAAM,CAAC;AACpD,CAAC"}

package/docs/figma-workflow.md

@@ -0,0 +1,289 @@
+# Figma to Code Workflow with DevLens
+
+This guide explains how to use DevLens together with Figma MCP to create a fully automated **design → code → verify → fix** loop for React Native development.
+
+---
+
+## Overview
+
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+│  Figma   │────►│   AI     │────►│  Code    │────►│  Device  │
+│  Design  │     │  Agent   │     │  Editor  │     │  Screen  │
+└──────────┘     └──────┬───┘     └──────────┘     └────┬─────┘
+                        │                                │
+                        │◄──── devlens_compare ──────────┘
+                        │      (similarity < 95%?)
+                        │               │
+                        ▼               ▼
+                   Fix Code ◄──── Diff Image
+```
+
+---
+
+## Prerequisites
+
+1. **Figma MCP** configured in your AI assistant (for reading designs)
+2. **DevLens MCP** configured (for device interaction) — see [Setup Guide](./setup-guide.md)
+3. **`FIGMA_TOKEN`** environment variable set (for `devlens_compare_with_figma`)
+4. **Metro bundler** running (`npx react-native start`)
+5. **Emulator/Simulator** running with your app loaded
+
+---
+
+## The Workflow — Step by Step
+
+### Step 1: Check Metro Health
+
+Before anything else, verify Metro is running and healthy:
+
+```
+devlens_metro_status
+→ Running: true, Port: 8081, Packager: running
+```
+
+If Metro is down, you'll get actionable instructions:
+```
+Metro is NOT running. Start it with:
+  cd your-project && npx react-native start
+```
+
+### Step 2: Get the Figma Design
+
+The AI reads the Figma design using Figma MCP. Two approaches for comparison:
+
+**Option A — Direct URL (Recommended):**
+Pass the Figma URL to `devlens_compare_with_figma` — it fetches the design via Figma REST API and compares automatically. One tool call, no piping.
+
+**Option B — File reference:**
+Export the Figma frame as PNG, save to your project (e.g., `./design-refs/home-screen.png`), and pass the path to `devlens_compare_screenshot`.
+
+### Step 3: Prompt the AI
+
+```
+Build the HomeScreen component based on this Figma design:
+[paste Figma URL]
+
+Use DevLens to verify the implementation matches the design.
+```
+
+### Step 4: The Automated Verification Loop
+
+The AI executes this loop:
+
+```
+1. devlens_metro_status              ← Verify Metro is healthy
+2. devlens_dismiss_overlays          ← Remove debug banners
+3. Generate/update React Native code
+4. devlens_hot_reload                ← Trigger Metro fast refresh
+5. devlens_wait_for_screen           ← Wait for screen to stabilize
+6. devlens_snapshot(validate: true)  ← Catch invisible/zero-size elements
+7. devlens_compare_with_figma        ← Compare with Figma design (one call)
+     (figmaUrl: "https://figma.com/design/...")
+8. Analyze diff image                ← Identify mismatches
+9. Fix code & repeat from step 4     ← Until similarity > 95%
+```
+
+Key improvements in v0.3.0:
+- **Step 2** removes React Native debug banners that ruin comparison scores
+- **Step 7** uses `devlens_compare_with_figma` — a single tool call that fetches the Figma design via REST API and compares. No base64 piping, no broken image pipeline.
+- **`cropRef`/`region`** on compare tools lets you ignore status bars and focus on specific areas
+
+### Step 5: AI Analyzes the Diff
+
+After comparison, the AI gets:
+- **Similarity score** (e.g., 72%)
+- **Diff image** with red highlights showing exactly where differences are
+- **Summary** categorizing the match quality
+
+The AI reads the diff image to identify specific issues (wrong font size, missing padding, incorrect color) and fixes them.
+
+---
+
+## Example Conversation
+
+```
+User: Build the login screen from Figma.
+      Figma URL: https://figma.com/design/abc123/MyApp?node-id=10-200
+
+AI: I'll start by checking Metro health and dismissing debug overlays.
+    [calls devlens_metro_status → Metro healthy on port 8081]
+    [calls devlens_dismiss_overlays → LogBox suppressed]
+    [calls get_design_context → reads colors, spacing, typography]
+
+    I'll create LoginScreen.tsx now.
+    [writes LoginScreen.tsx]
+    [calls devlens_hot_reload]
+    [calls devlens_wait_for_screen(stableMs: 1500)]
+    [calls devlens_snapshot(validate: true)]
+
+    Validation report: all elements visible, no issues.
+
+    [calls devlens_compare_with_figma(
+      figmaUrl: "https://figma.com/design/abc123/MyApp?node-id=10-200")]
+
+    Similarity: 72%. The diff shows:
+    - Title text is 18px but should be 24px
+    - Primary button color is #333 but should be #2563EB
+    - Bottom padding missing on form container
+
+    Fixing these issues...
+    [updates LoginScreen.tsx]
+    [calls devlens_hot_reload]
+    [calls devlens_wait_for_screen(stableMs: 1000)]
+    [calls devlens_compare_with_figma(
+      figmaUrl: "https://figma.com/design/abc123/MyApp?node-id=10-200")]
+
+    Similarity: 91%. Remaining: input border radius 8px → should be 12px.
+
+    [fixes border radius]
+    [calls devlens_hot_reload]
+    [calls devlens_wait_for_screen]
+    [calls devlens_compare_with_figma(
+      figmaUrl: "https://figma.com/design/abc123/MyApp?node-id=10-200")]
+
+    Similarity: 97%. The implementation matches the Figma design.
+```
+
+---
+
+## Pro Tips
+
+### 1. Always Start with Metro Status + Dismiss Overlays
+Call `devlens_metro_status` at the beginning of any session, then `devlens_dismiss_overlays` to remove React Native debug banners. This ensures clean screenshots for comparison. If Metro dies mid-session, call status again to diagnose.
+
+### 2. Use Validation Mode to Catch Invisible Elements
+When you notice a component is missing from the screenshot but you know the code renders it:
+```
+devlens_snapshot(validate: true)
+```
+This will flag zero-size elements, invisible nodes, and empty containers. Common causes:
+- Image with missing/broken source → renders as 0x0
+- `display: 'none'` or `opacity: 0` styles
+- Parent container collapsing due to missing flex
+
+### 3. Use Wait-for-Screen Instead of Sleep
+Instead of:
+```
+devlens_hot_reload → sleep 3 → devlens_screenshot
+```
+Use:
+```
+devlens_hot_reload → devlens_wait_for_screen(stableMs: 1500)
+```
+This waits only as long as needed (faster) and guarantees the screen has stopped changing (more reliable).
+
+### 4. Match Screenshot Dimensions
+Export your Figma design at the same dimensions as your emulator/simulator screen. DevLens will resize for comparison, but matching dimensions gives the most accurate results.
+
+If dimensions don't match, choose a resize strategy:
+- **`fit`** (default) — resize both to smaller dimensions
+- **`scale`** — resize smaller image up to larger
+- **`crop`** — compare only the overlapping region
+
+### 5. Use Element Screenshots for Components
+For comparing individual components (not full screens):
+```
+devlens_snapshot()                           → get refs
+devlens_element_screenshot(ref: "e5")        → screenshot just that component
+devlens_compare_screenshot(                  → compare against Figma component
+  referenceImageBase64: <figma_component_base64>
+)
+```
+
+### 6. Adjust Comparison Threshold
+The default threshold (0.1) works well for most cases:
+- **Strict matching** (exact colors): use `threshold: 0.05`
+- **Lenient matching** (layout only): use `threshold: 0.2`
+
+### 7. Use Incremental Snapshots in Loops
+After the first full snapshot, use `mode: "incremental"` to save tokens:
+```
+devlens_snapshot(mode: "full")         → first time
+devlens_snapshot(mode: "incremental")  → subsequent calls (only changes)
+```
+
+### 8. Check Metro Logs for Runtime Errors
+If the screen looks wrong, there might be runtime errors:
+```
+devlens_metro_logs(level: "error")
+```
+
+### 9. Use Capture Flow for Multi-Screen Verification
+Instead of calling tap → screenshot → back for each screen:
+```
+devlens_capture_flow(steps: [
+  { action: "tap", ref: "e5", element: "Tab 1" },
+  { action: "screenshot", label: "tab1-screen" },
+  { action: "tap", ref: "e6", element: "Tab 2" },
+  { action: "screenshot", label: "tab2-screen" },
+  { action: "tap", ref: "e7", element: "Tab 3" },
+  { action: "screenshot", label: "tab3-screen" }
+])
+```
+This returns all screenshots in a single call — saving ~12 tool calls for 4 screens.
+
+### 10. Use Layout Detection for Debugging
+When children are laid out incorrectly (horizontal vs vertical):
+```
+devlens_element_info(ref: "e3")
+→ Inferred Layout: row (children arranged left-to-right)
+```
+If it says `row` but your design expects `column`, you know the `flexDirection` is wrong.
+
+---
+
+## Combining with Other MCP Servers
+
+DevLens works great alongside:
+
+| MCP Server | Use |
+|-----------|-----|
+| **Figma MCP** | Read design specs, get screenshots as base64 for comparison |
+| **Playwright MCP** | Test web views or web versions of your app |
+| **GitHub MCP** | Create PRs with before/after screenshots |
+
+---
+
+## Troubleshooting
+
+### Similarity is always low (< 50%)
+- **Most common cause**: Figma presentation artifacts (rounded corners, grey backgrounds)
+  - **Solution**: Use `preprocessReference: true` (enabled by default for `devlens_compare_with_figma`)
+- Check that the reference image dimensions match the device screen
+- Ensure the correct screen is displayed on the device
+- Verify the app has fully loaded — use `devlens_wait_for_screen` before comparing
+- Try `resizeStrategy: "scale"` if the reference image is smaller than the device screen
+
+### Preprocessing removes too much or too little
+The preprocessing uses smart content detection, but you can control it:
+
+**If too aggressive** (removes actual content):
+```
+preprocessReference: false  // Disable preprocessing
+```
+
+**For debugging** (see what was removed):
+- Check the console output — it logs detected artifacts
+- Preprocessed dimensions are shown in comparison results
+
+**Known limitations**:
+- Works best when Figma export dimensions match device screen
+- Very complex backgrounds may confuse content detection
+- If similarity is still low after preprocessing, check for dimension mismatches
+
+### "Could not connect to Metro"
+- Run `devlens_metro_status` for a detailed health report
+- Metro must be running: `npx react-native start`
+- Check `METRO_PORT` matches your Metro config (default: 8081)
+
+### Hot reload doesn't seem to work
+- Verify Metro is watching your files (check Metro terminal output)
+- Use `devlens_wait_for_screen` after hot reload to confirm the screen updated
+- Try a full reload: `devlens_terminate_app` → `devlens_launch_app`
+- Check for syntax errors: `devlens_metro_logs(level: "error")`
+
+### Elements appear in code but not on screen
+- Run `devlens_snapshot(validate: true)` to check for zero-size or invisible elements
+- Use `devlens_find_element(text: "missing text")` — it will warn if the element exists but is invisible
+- Common causes: missing image source, parent overflow hidden, style width/height 0