visual-mirror 1.0.2

package/README.md

@@ -0,0 +1,109 @@
+# visual-mirror
+
+> Pixel diffs tell you something changed. Visual Mirror tells you what it means.
+
+[![npm version](https://img.shields.io/npm/v/visual-mirror.svg)](https://www.npmjs.com/package/visual-mirror)
+[![license](https://img.shields.io/npm/l/visual-mirror.svg)](LICENSE)
+
+A CLI tool for visual regression testing powered by AI. It captures a screenshot of a live URL, diffs it pixel-by-pixel against a reference image, then uses Claude Vision to provide an intelligent, human-readable analysis of what changed — complete with actionable fix suggestions.
+
+## Install
+
+```bash
+npm install -g visual-mirror
+```
+
+## Quick Start
+
+```bash
+# Option 1: Paste from clipboard — just copy a screenshot and run:
+visual-mirror --url http://localhost:3000
+
+# Option 2: Provide a reference file:
+visual-mirror --ref ./reference.png --url http://localhost:3000
+```
+
+## How It Works
+
+1. **Capture** — Takes a headless Chromium screenshot of your live URL via Playwright
+2. **Diff** — Compares the captured screenshot against your reference image pixel-by-pixel using Jimp, generating a visual diff overlay
+3. **Analyze** — Sends both screenshots to Claude Vision, which identifies specific UI issues (not just "something changed" — it tells you *what* changed)
+4. **Select** — Presents issues in an interactive terminal prompt (like `yay` on Arch) where you pick which ones to get fix suggestions for
+5. **Report** — Generates a self-contained HTML report with all three images, issues, and fix suggestions, then auto-opens it in your browser
+
+## Usage
+
+```bash
+visual-mirror --ref <path> --url <url> [options]
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--ref <path>` | Path to reference screenshot (PNG/JPG). If omitted, reads from clipboard | *optional* |
+| `--url <url>` | URL to capture and compare | *required* |
+| `--width <number>` | Viewport width in pixels | `1280` |
+| `--height <number>` | Viewport height in pixels | `720` |
+| `--out <path>` | Output directory for report | `./visual-mirror-report` |
+
+### Example
+
+```bash
+visual-mirror --ref ./designs/homepage.png --url http://localhost:3000 --width 1440 --height 900
+```
+
+### Interactive Flow
+
+After analysis, you'll see something like:
+
+```
+  Severity: MINOR
+
+  Issues found:
+    1  Button alignment shifted 8px to the right          .cta-button
+    2  Font color changed from #333 to #555               body
+    3  Hero image 12px taller than reference              .hero-image
+
+  ==> Select issues to get fix suggestions for (e.g. 1,2 or * for all)
+  ==> 1,3
+```
+
+Then you'll get targeted fix suggestions:
+
+```
+  Fix suggestions:
+
+  [1] Button alignment shifted 8px to the right
+      → Check margin-right on .cta-button, likely a padding change.
+        Try: padding-right: 16px;
+
+  [3] Hero image 12px taller than reference
+      → Set an explicit height on .hero-image: height: 320px;
+
+  ✔ Report saved to ./visual-mirror-report/index.html
+  Opening report...
+```
+
+## Environment Setup
+
+Set your Anthropic API key:
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key-here"
+```
+
+Get one at [console.anthropic.com](https://console.anthropic.com).
+
+## Publishing
+
+```bash
+npm login
+npm publish
+```
+
+The `prepublishOnly` script runs `tsc` automatically before publishing.
+
+## License
+
+MIT

package/dist/analyze.d.ts

@@ -0,0 +1,22 @@
+export type Issue = {
+    id: number;
+    title: string;
+    description: string;
+    area: string;
+};
+export type Severity = "OK" | "MINOR" | "MAJOR";
+export type AnalysisResult = {
+    severity: Severity;
+    verdict: string;
+    issues: Issue[];
+};
+export type Fix = {
+    id: number;
+    title: string;
+    suggestion: string;
+};
+export type FixResult = {
+    fixes: Fix[];
+};
+export declare function analyzeScreenshots(referencePath: string, capturedPath: string): Promise<AnalysisResult>;
+export declare function getFixSuggestions(issues: Issue[]): Promise<FixResult>;

package/dist/analyze.js

@@ -0,0 +1,105 @@
+import Anthropic from "@anthropic-ai/sdk";
+import fs from "node:fs";
+import chalk from "chalk";
+function imageToBase64(filePath) {
+    return fs.readFileSync(filePath).toString("base64");
+}
+function getMediaType(filePath) {
+    const ext = filePath.toLowerCase().split(".").pop();
+    if (ext === "jpg" || ext === "jpeg")
+        return "image/jpeg";
+    if (ext === "webp")
+        return "image/webp";
+    if (ext === "gif")
+        return "image/gif";
+    return "image/png";
+}
+export async function analyzeScreenshots(referencePath, capturedPath) {
+    const client = new Anthropic();
+    const refBase64 = imageToBase64(referencePath);
+    const capBase64 = imageToBase64(capturedPath);
+    const refMediaType = getMediaType(referencePath);
+    const capMediaType = getMediaType(capturedPath);
+    const response = await client.messages.create({
+        model: "claude-sonnet-4-20250514",
+        max_tokens: 4096,
+        system: "You are a visual QA engineer reviewing UI screenshots.",
+        messages: [
+            {
+                role: "user",
+                content: [
+                    {
+                        type: "image",
+                        source: {
+                            type: "base64",
+                            media_type: refMediaType,
+                            data: refBase64,
+                        },
+                    },
+                    {
+                        type: "image",
+                        source: {
+                            type: "base64",
+                            media_type: capMediaType,
+                            data: capBase64,
+                        },
+                    },
+                    {
+                        type: "text",
+                        text: `Compare these two screenshots. First is the reference/expected design. Second is the actual rendered result.
+Return ONLY valid JSON with no markdown or backticks:
+{
+  "severity": "OK" | "MINOR" | "MAJOR",
+  "verdict": "string",
+  "issues": [
+    {
+      "id": number,
+      "title": "string",
+      "description": "string",
+      "area": "string"
+    }
+  ]
+}
+Each issue should be atomic and specific (e.g. 'Button shifted 8px right', not 'Layout problems'). area should be a CSS selector or component name if identifiable.
+If the screenshots look identical, return severity "OK" with an empty issues array.`,
+                    },
+                ],
+            },
+        ],
+    });
+    const text = response.content[0].type === "text" ? response.content[0].text : "";
+    console.log(chalk.green("✔") + " Analyzing with Claude...");
+    const result = JSON.parse(text);
+    return result;
+}
+export async function getFixSuggestions(issues) {
+    const client = new Anthropic();
+    const response = await client.messages.create({
+        model: "claude-sonnet-4-20250514",
+        max_tokens: 4096,
+        messages: [
+            {
+                role: "user",
+                content: `You are a senior frontend developer. For each of the following visual issues found in a UI screenshot comparison, provide a specific, actionable CSS or code fix suggestion. Be concrete — reference property names, values, and selectors where possible.
+
+Issues:
+${JSON.stringify(issues, null, 2)}
+
+Return ONLY valid JSON with no markdown:
+{
+  "fixes": [
+    {
+      "id": number,
+      "title": "string",
+      "suggestion": "string"
+    }
+  ]
+}`,
+            },
+        ],
+    });
+    const text = response.content[0].type === "text" ? response.content[0].text : "";
+    const result = JSON.parse(text);
+    return result;
+}
+//# sourceMappingURL=analyze.js.map

package/dist/analyze.js.map

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

package/dist/capture.d.ts

@@ -0,0 +1 @@
+export declare function captureScreenshot(url: string, outputDir: string, width: number, height: number): Promise<string>;

package/dist/capture.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import chalk from "chalk";
+async function ensureChromium() {
+    const { chromium } = await import("playwright");
+    const execPath = chromium.executablePath();
+    if (!fs.existsSync(execPath)) {
+        console.log(chalk.yellow("⚙") + " Chromium not found. Installing via Playwright...");
+        try {
+            execSync("npx playwright install chromium", { stdio: "inherit" });
+            console.log(chalk.green("✔") + " Chromium installed successfully.");
+        }
+        catch {
+            console.error(chalk.red("Failed to install Chromium. Try running manually:\n") +
+                chalk.cyan("  npx playwright install chromium"));
+            process.exit(1);
+        }
+    }
+}
+export async function captureScreenshot(url, outputDir, width, height) {
+    await ensureChromium();
+    const { chromium } = await import("playwright");
+    const screenshotPath = path.join(outputDir, "captured.png");
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const context = await browser.newContext({
+            viewport: { width, height },
+            ignoreHTTPSErrors: true,
+        });
+        const page = await context.newPage();
+        await page.goto(url, { waitUntil: "networkidle", timeout: 30000 });
+        await page.screenshot({ path: screenshotPath, fullPage: false });
+        console.log(chalk.green("✔") + ` Captured screenshot from ${chalk.cyan(url)}`);
+    }
+    finally {
+        await browser.close();
+    }
+    return screenshotPath;
+}
+//# sourceMappingURL=capture.js.map

package/dist/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,KAAK,UAAU,cAAc;IAC3B,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC;IAE3C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,mDAAmD,CAAC,CAAC;QACrF,IAAI,CAAC;YACH,QAAQ,CAAC,iCAAiC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YAClE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,mCAAmC,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,KAAK,CACX,KAAK,CAAC,GAAG,CAAC,qDAAqD,CAAC;gBAC9D,KAAK,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAClD,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,SAAiB,EACjB,KAAa,EACb,MAAc;IAEd,MAAM,cAAc,EAAE,CAAC;IAEvB,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAE5D,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;YACvC,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;YAC3B,iBAAiB,EAAE,IAAI;SACxB,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAErC,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACnE,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QAEjE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,6BAA6B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjF,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/clipboard.d.ts

@@ -0,0 +1 @@
+export declare function readClipboardImage(outputDir: string): Promise<string>;

package/dist/clipboard.js

@@ -0,0 +1,109 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { input } from "@inquirer/prompts";
+function hasCommand(name) {
+    try {
+        execSync(`which ${name}`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getLinuxClipboardTools() {
+    const tools = [];
+    // wl-paste is preferred on Wayland but xclip works too (via XWayland)
+    if (hasCommand("wl-paste")) {
+        tools.push({ cmd: "wl-paste --type image/png", name: "wl-paste" });
+    }
+    if (hasCommand("xclip")) {
+        tools.push({ cmd: "xclip -selection clipboard -target image/png -o", name: "xclip" });
+    }
+    if (hasCommand("xsel")) {
+        tools.push({ cmd: "xsel --clipboard --output", name: "xsel" });
+    }
+    return tools;
+}
+function tryReadClipboard(tool) {
+    try {
+        const buf = execSync(tool.cmd, {
+            maxBuffer: 50 * 1024 * 1024,
+            stdio: ["pipe", "pipe", "ignore"],
+        });
+        if (buf.length > 0)
+            return buf;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readClipboardImage(outputDir) {
+    let tools = [];
+    if (process.platform === "darwin") {
+        if (hasCommand("pngpaste")) {
+            tools.push({ cmd: "pngpaste -", name: "pngpaste" });
+        }
+        if (hasCommand("osascript")) {
+            // pbpaste doesn't support images, but osascript can write clipboard image to a file
+            const tmpPath = path.join(outputDir, "clipboard-ref.png");
+            tools.push({
+                cmd: `osascript -e 'try' -e 'set imgData to the clipboard as «class PNGf»' -e 'set fp to open for access POSIX file "${tmpPath}" with write permission' -e 'write imgData to fp' -e 'close access fp' -e 'end try'`,
+                name: "osascript",
+            });
+        }
+    }
+    else if (process.platform === "linux") {
+        tools = getLinuxClipboardTools();
+    }
+    else if (process.platform === "win32") {
+        tools.push({
+            cmd: `powershell -command "Add-Type -AssemblyName System.Windows.Forms; $img = [System.Windows.Forms.Clipboard]::GetImage(); if ($img) { $img.Save([Console]::OpenStandardOutput(), [System.Drawing.Imaging.ImageFormat]::Png) } else { exit 1 }"`,
+            name: "powershell",
+        });
+    }
+    if (tools.length === 0) {
+        console.error(chalk.red("No clipboard tool found.\n") +
+            chalk.dim("  Install one of: wl-clipboard, xclip, xsel\n") +
+            chalk.cyan("  sudo pacman -S xclip          # Arch\n") +
+            chalk.cyan("  sudo apt install xclip        # Debian/Ubuntu"));
+        process.exit(1);
+    }
+    // Try each available tool until one returns image data
+    for (const tool of tools) {
+        const buf = tryReadClipboard(tool);
+        if (buf) {
+            fs.mkdirSync(outputDir, { recursive: true });
+            const outPath = path.join(outputDir, "clipboard-ref.png");
+            fs.writeFileSync(outPath, buf);
+            console.log(chalk.green("✔") +
+                ` Read reference image from clipboard via ${tool.name} (${(buf.length / 1024).toFixed(0)} KB)`);
+            return outPath;
+        }
+    }
+    console.log(chalk.yellow("⚙") + " No image found in clipboard.");
+    console.log(chalk.dim("  You can drag & drop an image file into this terminal, or paste its path.\n"));
+    const filePath = await input({
+        message: "Path to reference image (drag file here or paste path):",
+    });
+    const cleaned = filePath.trim().replace(/^['"]|['"]$/g, "");
+    if (!cleaned || !fs.existsSync(cleaned)) {
+        console.error(chalk.red("File not found: ") + chalk.dim(cleaned || "(empty)"));
+        process.exit(1);
+    }
+    const ext = path.extname(cleaned).toLowerCase();
+    if (![".png", ".jpg", ".jpeg", ".webp", ".bmp"].includes(ext)) {
+        console.error(chalk.red("Unsupported image format: ") + chalk.dim(ext));
+        process.exit(1);
+    }
+    fs.mkdirSync(outputDir, { recursive: true });
+    const outPath = path.join(outputDir, "clipboard-ref" + ext);
+    fs.copyFileSync(cleaned, outPath);
+    const size = fs.statSync(outPath).size;
+    console.log(chalk.green("✔") +
+        ` Using reference image: ${chalk.cyan(path.basename(cleaned))} (${(size / 1024).toFixed(0)} KB)`);
+    return outPath;
+}
+//# sourceMappingURL=clipboard.js.map

package/dist/clipboard.js.map

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

package/dist/diff.d.ts

@@ -0,0 +1,5 @@
+export type DiffResult = {
+    diffPath: string;
+    diffPercent: number;
+};
+export declare function runDiff(referencePath: string, capturedPath: string, outputDir: string): Promise<DiffResult>;

package/dist/diff.js

@@ -0,0 +1,62 @@
+import { createJimp } from "@jimp/core";
+import png from "@jimp/js-png";
+import jpeg from "@jimp/js-jpeg";
+import * as resize from "@jimp/plugin-resize";
+import path from "node:path";
+import chalk from "chalk";
+const Jimp = createJimp({ formats: [png, jpeg], plugins: [resize.methods] });
+export async function runDiff(referencePath, capturedPath, outputDir) {
+    const refImage = await Jimp.read(referencePath);
+    const capImage = await Jimp.read(capturedPath);
+    const width = capImage.width;
+    const height = capImage.height;
+    // Resize reference to match captured dimensions if they differ
+    if (refImage.width !== width || refImage.height !== height) {
+        refImage.resize({ w: width, h: height });
+    }
+    const diffImage = new Jimp({ width, height });
+    const threshold = 0.1;
+    let diffPixels = 0;
+    const totalPixels = width * height;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const refColor = refImage.getPixelColor(x, y);
+            const capColor = capImage.getPixelColor(x, y);
+            if (refColor !== capColor) {
+                // Extract RGBA components
+                const rRef = (refColor >> 24) & 0xff;
+                const gRef = (refColor >> 16) & 0xff;
+                const bRef = (refColor >> 8) & 0xff;
+                const rCap = (capColor >> 24) & 0xff;
+                const gCap = (capColor >> 16) & 0xff;
+                const bCap = (capColor >> 8) & 0xff;
+                const maxDiff = Math.max(Math.abs(rRef - rCap), Math.abs(gRef - gCap), Math.abs(bRef - bCap));
+                if (maxDiff / 255 > threshold) {
+                    // Highlight difference in red
+                    diffImage.setPixelColor(0xff0000ff, x, y);
+                    diffPixels++;
+                }
+                else {
+                    // Below threshold — show faded original
+                    const gray = Math.round((rCap + gCap + bCap) / 3);
+                    diffImage.setPixelColor(((gray << 24) | (gray << 16) | (gray << 8) | 0x80) >>> 0, x, y);
+                }
+            }
+            else {
+                // Identical pixel — show faded
+                const r = (capColor >> 24) & 0xff;
+                const g = (capColor >> 16) & 0xff;
+                const b = (capColor >> 8) & 0xff;
+                const gray = Math.round((r + g + b) / 3);
+                diffImage.setPixelColor(((gray << 24) | (gray << 16) | (gray << 8) | 0x80) >>> 0, x, y);
+            }
+        }
+    }
+    const diffPath = path.join(outputDir, "diff.png");
+    await diffImage.write(diffPath);
+    const diffPercent = (diffPixels / totalPixels) * 100;
+    console.log(chalk.green("✔") +
+        ` Running pixel diff... (${chalk.yellow(diffPercent.toFixed(1) + "%")} difference)`);
+    return { diffPath, diffPercent };
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "node:fs";
+import https from "node:https";
+import path from "node:path";
+import chalk from "chalk";
+import open from "open";
+import { input, password } from "@inquirer/prompts";
+import { captureScreenshot } from "./capture.js";
+import { readClipboardImage } from "./clipboard.js";
+import { runDiff } from "./diff.js";
+import { analyzeScreenshots } from "./analyze.js";
+import { runInteractive } from "./interactive.js";
+import { generateReport } from "./report.js";
+const program = new Command();
+program
+    .name("visual-mirror")
+    .description("Pixel diffs tell you something changed. Visual Mirror tells you what it means.")
+    .version("1.0.0")
+    .option("--ref <path>", "Path to reference screenshot (PNG/JPG). If omitted, reads from clipboard")
+    .requiredOption("--url <url>", "URL to capture and compare")
+    .option("--width <number>", "Viewport width", "1280")
+    .option("--height <number>", "Viewport height", "720")
+    .option("--out <path>", "Output directory for report", "./visual-mirror-report");
+program.parse();
+const opts = program.opts();
+async function ensureApiKey() {
+    if (process.env.ANTHROPIC_API_KEY)
+        return;
+    console.log(chalk.yellow("⚙") + " ANTHROPIC_API_KEY not found in your environment.");
+    console.log(chalk.dim("  Get one at https://console.anthropic.com\n"));
+    const key = await password({
+        message: "Enter your Anthropic API key:",
+        mask: "*",
+    });
+    const trimmed = key.trim();
+    if (!trimmed) {
+        console.error(chalk.red("No API key provided. Exiting."));
+        process.exit(1);
+    }
+    process.env.ANTHROPIC_API_KEY = trimmed;
+    const shell = path.basename(process.env.SHELL || "bash");
+    const rcFile = shell === "zsh" ? "~/.zshrc" : shell === "fish" ? "~/.config/fish/config.fish" : "~/.bashrc";
+    const exportCmd = shell === "fish"
+        ? `set -Ux ANTHROPIC_API_KEY "${trimmed}"`
+        : `export ANTHROPIC_API_KEY="${trimmed}"`;
+    console.log();
+    console.log(chalk.green("✔") + " API key set for this session.");
+    console.log(chalk.dim("  To persist it, add this to ") + chalk.cyan(rcFile) + chalk.dim(":"));
+    console.log(chalk.dim(`  ${exportCmd}`));
+    console.log();
+}
+async function tryUrl(url) {
+    try {
+        if (url.startsWith("https://")) {
+            // Use node:https to allow self-signed certs (common for local dev servers)
+            return await new Promise((resolve) => {
+                const req = https.get(url, { rejectUnauthorized: false, timeout: 5000 }, (res) => {
+                    res.resume();
+                    resolve(true);
+                });
+                req.on("error", () => resolve(false));
+                req.on("timeout", () => {
+                    req.destroy();
+                    resolve(false);
+                });
+            });
+        }
+        await fetch(url, { signal: AbortSignal.timeout(5000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveUrl(url) {
+    if (await tryUrl(url))
+        return url;
+    // Try alternative ports if the URL has a port
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url; // Let it fail later with a proper error
+    }
+    if (parsed.port) {
+        const basePort = parseInt(parsed.port, 10);
+        const alternatives = [basePort + 1, basePort - 1, 8080, 3000, 5173, 4200, 8000];
+        const uniquePorts = [
+            ...new Set(alternatives.filter((p) => p !== basePort && p > 0 && p <= 65535)),
+        ];
+        console.log(chalk.yellow("⚙") + ` Could not reach ${chalk.cyan(url)}. Trying nearby ports...`);
+        for (const port of uniquePorts) {
+            const alt = new URL(url);
+            alt.port = String(port);
+            const altUrl = alt.toString();
+            if (await tryUrl(altUrl)) {
+                console.log(chalk.green("✔") + ` Found live server at ${chalk.cyan(altUrl)}`);
+                const answer = await input({
+                    message: `Use ${altUrl} instead? (Y/n)`,
+                    default: "Y",
+                });
+                if (answer.trim().toLowerCase() !== "n") {
+                    return altUrl;
+                }
+            }
+        }
+    }
+    // Nothing worked — give the user instructions
+    console.error(chalk.red(`\nCould not reach ${url}`));
+    console.error(chalk.dim("  Make sure your app is running. For example:\n"));
+    console.error(chalk.dim("  # React / Vite / Next.js"));
+    console.error(chalk.cyan("  npm run dev\n"));
+    console.error(chalk.dim("  # Quick static file server"));
+    console.error(chalk.cyan("  npx serve ./dist -p 3000\n"));
+    console.error(chalk.dim("  # Python"));
+    console.error(chalk.cyan("  python -m http.server 3000\n"));
+    process.exit(1);
+}
+async function main() {
+    // Step 0: Ensure API key
+    await ensureApiKey();
+    const width = parseInt(opts.width, 10);
+    const height = parseInt(opts.height, 10);
+    const outputDir = path.resolve(opts.out);
+    // Resolve reference: from --ref flag or clipboard
+    let refPath;
+    if (opts.ref) {
+        refPath = path.resolve(opts.ref);
+        if (!fs.existsSync(refPath)) {
+            console.error(chalk.red(`Reference file not found: ${refPath}`));
+            process.exit(1);
+        }
+    }
+    else {
+        console.log(chalk.yellow("⚙") + " No --ref provided. Reading reference image from clipboard...");
+        refPath = await readClipboardImage(outputDir);
+    }
+    // Ensure output directory exists
+    fs.mkdirSync(outputDir, { recursive: true });
+    // Step 1: Resolve URL (check reachability, try alt ports)
+    const resolvedUrl = await resolveUrl(opts.url);
+    // Step 2: Capture screenshot
+    let capturedPath;
+    try {
+        capturedPath = await captureScreenshot(resolvedUrl, outputDir, width, height);
+    }
+    catch (err) {
+        console.error(chalk.red(`Could not capture screenshot from ${resolvedUrl}`));
+        console.error(chalk.dim(String(err)));
+        process.exit(1);
+    }
+    // Step 3: Pixel diff
+    const { diffPath, diffPercent } = await runDiff(refPath, capturedPath, outputDir);
+    // Step 4: Claude Vision analysis
+    let analysis;
+    try {
+        analysis = await analyzeScreenshots(refPath, capturedPath);
+    }
+    catch (err) {
+        console.error(chalk.red("Claude API error:"), err);
+        process.exit(1);
+    }
+    // Step 5: Interactive selection + fix suggestions
+    const fixes = await runInteractive(analysis);
+    // Step 6: Generate report
+    const reportPath = generateReport(resolvedUrl, refPath, capturedPath, diffPath, diffPercent, analysis, fixes, outputDir);
+    console.log(chalk.green("✔") + ` Report saved to ${chalk.cyan(reportPath)}`);
+    console.log("  Opening report...");
+    await open(reportPath);
+}
+main().catch((err) => {
+    if (err instanceof Error && err.name === "ExitPromptError") {
+        console.log("\nAborted.");
+        process.exit(0);
+    }
+    console.error(chalk.red("Unexpected error:"), err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/interactive.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult, Fix } from "./analyze.js";
+export declare function runInteractive(analysis: AnalysisResult): Promise<Fix[]>;

package/dist/interactive.js

@@ -0,0 +1,84 @@
+import chalk from "chalk";
+import { input } from "@inquirer/prompts";
+import { getFixSuggestions } from "./analyze.js";
+function severityColor(severity) {
+    switch (severity) {
+        case "OK":
+            return chalk.green(severity);
+        case "MINOR":
+            return chalk.yellow(severity);
+        case "MAJOR":
+            return chalk.red(severity);
+        default:
+            return severity;
+    }
+}
+function displayResults(analysis) {
+    console.log();
+    console.log(`  Severity: ${severityColor(analysis.severity)}`);
+    console.log();
+    if (analysis.issues.length === 0) {
+        console.log(chalk.green("  No issues found — screenshots match!"));
+        console.log();
+        return;
+    }
+    console.log("  Issues found:");
+    for (const issue of analysis.issues) {
+        const id = chalk.white(String(issue.id).padStart(3));
+        const title = chalk.white(issue.title.padEnd(55));
+        const area = chalk.dim(issue.area);
+        console.log(`  ${id}  ${title} ${area}`);
+    }
+    console.log();
+}
+function parseSelection(input, maxId) {
+    const trimmed = input.trim();
+    if (trimmed === "*") {
+        return Array.from({ length: maxId }, (_, i) => i + 1);
+    }
+    const parts = trimmed.split(",").map((s) => s.trim());
+    const ids = [];
+    for (const part of parts) {
+        const num = parseInt(part, 10);
+        if (isNaN(num) || num < 1 || num > maxId) {
+            return null;
+        }
+        ids.push(num);
+    }
+    return ids.length > 0 ? [...new Set(ids)] : null;
+}
+export async function runInteractive(analysis) {
+    displayResults(analysis);
+    if (analysis.issues.length === 0) {
+        return [];
+    }
+    let selectedIds = null;
+    while (selectedIds === null) {
+        const answer = await input({
+            message: chalk.cyan("==>") +
+                " Select issues to get fix suggestions for (e.g. 1,2 or * for all)\n" +
+                chalk.cyan("==>"),
+        });
+        selectedIds = parseSelection(answer, analysis.issues.length);
+        if (selectedIds === null) {
+            console.log(chalk.red("  Invalid selection. Enter issue numbers separated by commas, or * for all."));
+        }
+    }
+    const selectedIssues = analysis.issues.filter((issue) => selectedIds.includes(issue.id));
+    console.log();
+    console.log(chalk.dim("  Fetching fix suggestions from Claude..."));
+    const fixResult = await getFixSuggestions(selectedIssues);
+    console.log();
+    console.log("  Fix suggestions:");
+    console.log();
+    for (const fix of fixResult.fixes) {
+        console.log(chalk.white(`  [${fix.id}] ${fix.title}`));
+        const lines = fix.suggestion.split("\n");
+        for (const line of lines) {
+            console.log(chalk.dim(`      → ${line}`));
+        }
+        console.log();
+    }
+    return fixResult.fixes;
+}
+//# sourceMappingURL=interactive.js.map

package/dist/interactive.js.map

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

package/dist/report.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult, Fix } from "./analyze.js";
+export declare function generateReport(url: string, referencePath: string, capturedPath: string, diffPath: string, diffPercent: number, analysis: AnalysisResult, fixes: Fix[], outputDir: string): string;

package/dist/report.js

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import path from "node:path";
+function imageToDataUrl(filePath) {
+    const data = fs.readFileSync(filePath).toString("base64");
+    const ext = filePath.toLowerCase().split(".").pop();
+    const mime = ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "image/png";
+    return `data:${mime};base64,${data}`;
+}
+function severityBadge(severity) {
+    const colors = {
+        OK: "#22c55e",
+        MINOR: "#eab308",
+        MAJOR: "#ef4444",
+    };
+    const color = colors[severity] || "#6b7280";
+    return `<span style="background:${color};color:#000;padding:4px 12px;border-radius:4px;font-weight:bold;">${severity}</span>`;
+}
+export function generateReport(url, referencePath, capturedPath, diffPath, diffPercent, analysis, fixes, outputDir) {
+    const timestamp = new Date().toISOString();
+    const refDataUrl = imageToDataUrl(referencePath);
+    const capDataUrl = imageToDataUrl(capturedPath);
+    const diffDataUrl = imageToDataUrl(diffPath);
+    const issuesHtml = analysis.issues
+        .map((issue) => `
+      <div style="background:#1e1e2e;padding:12px 16px;border-radius:6px;margin-bottom:8px;">
+        <strong style="color:#cdd6f4;">#${issue.id} ${issue.title}</strong>
+        <span style="color:#6c7086;margin-left:12px;">${issue.area}</span>
+        <p style="color:#a6adc8;margin:6px 0 0;">${issue.description}</p>
+      </div>`)
+        .join("\n");
+    let fixesHtml;
+    if (fixes.length === 0) {
+        fixesHtml = `<p style="color:#6c7086;font-style:italic;">No fixes requested.</p>`;
+    }
+    else {
+        fixesHtml = fixes
+            .map((fix) => `
+      <div style="background:#1e1e2e;padding:12px 16px;border-radius:6px;margin-bottom:8px;">
+        <strong style="color:#cdd6f4;">[${fix.id}] ${fix.title}</strong>
+        <pre style="color:#a6e3a1;margin:8px 0 0;white-space:pre-wrap;font-size:13px;">${fix.suggestion}</pre>
+      </div>`)
+            .join("\n");
+    }
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Visual Mirror Report</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      background: #11111b;
+      color: #cdd6f4;
+      font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace;
+      padding: 32px;
+      line-height: 1.6;
+    }
+    h1 { color: #cba6f7; font-size: 24px; margin-bottom: 8px; }
+    h2 { color: #89b4fa; font-size: 18px; margin: 32px 0 16px; }
+    .header-meta {
+      color: #6c7086;
+      font-size: 13px;
+      margin-bottom: 24px;
+    }
+    .header-meta span { margin-right: 24px; }
+    .image-grid {
+      display: grid;
+      grid-template-columns: 1fr 1fr 1fr;
+      gap: 16px;
+      margin-bottom: 32px;
+    }
+    .image-grid div {
+      text-align: center;
+    }
+    .image-grid img {
+      width: 100%;
+      border: 1px solid #313244;
+      border-radius: 6px;
+    }
+    .image-grid p {
+      color: #6c7086;
+      font-size: 12px;
+      margin-top: 8px;
+    }
+  </style>
+</head>
+<body>
+  <h1>Visual Mirror Report</h1>
+  <div class="header-meta">
+    <span>URL: ${url}</span>
+    <span>Time: ${timestamp}</span>
+    <span>Diff: ${diffPercent.toFixed(1)}%</span>
+    <span>${severityBadge(analysis.severity)}</span>
+  </div>
+
+  <h2>Screenshots</h2>
+  <div class="image-grid">
+    <div>
+      <img src="${refDataUrl}" alt="Reference">
+      <p>Reference</p>
+    </div>
+    <div>
+      <img src="${capDataUrl}" alt="Captured">
+      <p>Captured</p>
+    </div>
+    <div>
+      <img src="${diffDataUrl}" alt="Diff">
+      <p>Diff</p>
+    </div>
+  </div>
+
+  <h2>Issues (${analysis.issues.length})</h2>
+  ${issuesHtml || '<p style="color:#a6e3a1;">No issues detected.</p>'}
+
+  <h2>Fix Suggestions</h2>
+  ${fixesHtml}
+
+  <p style="color:#45475a;margin-top:48px;font-size:11px;">Generated by visual-mirror</p>
+</body>
+</html>`;
+    const reportPath = path.join(outputDir, "index.html");
+    fs.writeFileSync(reportPath, html, "utf-8");
+    return reportPath;
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,SAAS,cAAc,CAAC,QAAgB;IACtC,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IACpD,MAAM,IAAI,GAAG,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;IAC1E,OAAO,QAAQ,IAAI,WAAW,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,SAAS,aAAa,CAAC,QAAgB;IACrC,MAAM,MAAM,GAA2B;QACrC,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,SAAS;KACjB,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC;IAC5C,OAAO,2BAA2B,KAAK,qEAAqE,QAAQ,SAAS,CAAC;AAChI,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,aAAqB,EACrB,YAAoB,EACpB,QAAgB,EAChB,WAAmB,EACnB,QAAwB,EACxB,KAAY,EACZ,SAAiB;IAEjB,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,UAAU,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,WAAW,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE7C,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM;SAC/B,GAAG,CACF,CAAC,KAAK,EAAE,EAAE,CAAC;;0CAEyB,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,KAAK;wDACT,KAAK,CAAC,IAAI;mDACf,KAAK,CAAC,WAAW;aACvD,CACR;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,IAAI,SAAiB,CAAC;IACtB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,SAAS,GAAG,qEAAqE,CAAC;IACpF,CAAC;SAAM,CAAC;QACN,SAAS,GAAG,KAAK;aACd,GAAG,CACF,CAAC,GAAG,EAAE,EAAE,CAAC;;0CAEyB,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,KAAK;yFAC2B,GAAG,CAAC,UAAU;aAC1F,CACN;aACA,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+CE,GAAG;kBACF,SAAS;kBACT,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5B,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC;;;;;;kBAM1B,UAAU;;;;kBAIV,UAAU;;;;kBAIV,WAAW;;;;;gBAKb,QAAQ,CAAC,MAAM,CAAC,MAAM;IAClC,UAAU,IAAI,mDAAmD;;;IAGjE,SAAS;;;;QAIL,CAAC;IAEP,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACtD,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "visual-mirror",
+  "version": "1.0.2",
+  "description": "Pixel diffs tell you something changed. Visual Mirror tells you what it means.",
+  "type": "module",
+  "main": "dist/index.js",
+  "author": {
+    "email": "kaweh.taher.1989@gmail.com",
+    "name": "Kaveh Taher",
+    "url": "https://github.com/kawehtaher"
+  },
+  "bin": {
+    "visual-mirror": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write 'src/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.ts'",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run lint && npm run format:check",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "visual-regression",
+    "screenshot",
+    "diff",
+    "testing",
+    "ai",
+    "claude"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "inquirer": "^12.6.0",
+    "jimp": "^1.6.0",
+    "open": "^10.1.0",
+    "playwright": "^1.52.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.15.2",
+    "eslint": "^10.2.0",
+    "prettier": "^3.8.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.58.0"
+  }
+}