@vscode/component-explorer-cli 0.1.1-5 → 0.1.1-7

package/README.md

@@ -0,0 +1,177 @@
+# @vscode/component-explorer-cli
+
+Command-line tool for capturing, comparing, and managing component fixture screenshots.
+
+## Installation
+
+```bash
+npm install @vscode/component-explorer-cli
+```
+
+The binary is available as `component-explorer`.
+
+## Commands
+
+### `screenshot`
+
+Capture screenshots of all fixtures using a headless browser.
+
+```bash
+component-explorer screenshot [options]
+```
+
+| Option | Description |
+|---|---|
+| `-p, --project <path>` | Project: a directory, vite config file, or component-explorer.json (default: cwd) |
+| `--filter <pattern>` | Filter fixtures by glob pattern |
+| `--accept` | Write to baseline instead of current (mutually exclusive with `--target`) |
+| `--target <dir>` | Screenshot output directory (default: `.screenshots/current`, or `.screenshots/baseline` with `--accept`) |
+| `--compare` | Compare screenshots after capturing |
+| `--compare-target <dir>` | Directory to compare against (default: `.screenshots/baseline`, or `.screenshots/current` with `--accept`) |
+| `--report <dir>` | Output report folder with report.json, report.md, and changed screenshots (requires `--compare`) |
+| `-v, --verbose` | Increase log verbosity (`-v` debug, `-vv` trace) |
+
+```bash
+# Capture all fixtures
+component-explorer screenshot
+
+# Capture and accept as baseline
+component-explorer screenshot --accept
+
+# Capture, then compare against baseline
+component-explorer screenshot --compare
+
+# Filter by glob
+component-explorer screenshot --filter "Button/*"
+```
+
+### `screenshot:compare`
+
+Compare two screenshot directories (file-level hash comparison).
+
+```bash
+component-explorer screenshot:compare [options]
+```
+
+| Option | Description |
+|---|---|
+| `-p, --project <path>` | Project directory (default: cwd) |
+| `--baseline <dir>` | Baseline screenshots directory (default: `.screenshots/baseline`) |
+| `--current <dir>` | Current screenshots directory (default: `.screenshots/current`) |
+| `--filter <pattern>` | Filter fixtures by glob pattern |
+| `--report <dir>` | Output report folder (contains report.json, report.md, and changed screenshots) |
+| `-v, --verbose` | Increase log verbosity |
+
+Exits with code 1 if differences are found, 0 otherwise.
+
+```bash
+# Compare default directories
+component-explorer screenshot:compare
+
+# Compare with custom paths
+component-explorer screenshot:compare --baseline ./golden --current ./actual
+
+# Generate report folder
+component-explorer screenshot:compare --report ./report
+```
+
+### `screenshot:accept`
+
+Promote current screenshots to baseline by copying them from `.screenshots/current` to `.screenshots/baseline`.
+
+```bash
+component-explorer screenshot:accept [options]
+```
+
+| Option | Description |
+|---|---|
+| `-p, --project <path>` | Project directory (default: cwd) |
+| `--filter <pattern>` | Filter fixtures by glob pattern |
+| `--screenshot-dir <dir>` | Screenshots directory (default: `.screenshots`) |
+| `-v, --verbose` | Increase log verbosity |
+
+```bash
+# Accept all current screenshots as baseline
+component-explorer screenshot:accept
+
+# Accept specific fixtures
+component-explorer screenshot:accept --filter "Button/*"
+```
+
+### `watch`
+
+Watch for source changes and automatically re-capture/compare screenshots. Supports both simple mode (single project) and config mode (multiple sessions with git worktrees).
+
+```bash
+component-explorer watch [options]
+```
+
+| Option | Description |
+|---|---|
+| `-p, --project <path>` | Project: a directory, vite config file, or component-explorer.json (default: cwd) |
+| `-v, --verbose` | Increase log verbosity |
+
+In simple mode, starts a Vite dev server and re-captures screenshots on every HMR update. In config mode (when given a `component-explorer.json`), manages multiple sessions including git worktree-based baselines.
+
+```bash
+# Watch all fixtures
+component-explorer watch
+
+# Watch with config
+component-explorer watch -p component-explorer.json
+```
+
+### `serve`
+
+Start or attach to a Component Explorer daemon process. The daemon manages Vite servers and browser sessions in the background.
+
+```bash
+component-explorer serve -p <config> [options]
+```
+
+| Option | Description |
+|---|---|
+| `-p, --project, -c <path>` | **(required)** Path to a component-explorer.json config file |
+| `--background` | Spawn as a detached background process |
+| `--attach` | Attach to a running daemon and stream events |
+| `--kill` | Shut down a running daemon |
+| `-v, --verbose` | Increase log verbosity |
+
+Without flags, starts a foreground daemon. Combine `--background` and `--attach` to ensure a daemon is running and then stream its events.
+
+```bash
+# Start in foreground
+component-explorer serve -p config.json
+
+# Start in background
+component-explorer serve -p config.json --background
+
+# Attach to running daemon
+component-explorer serve -p config.json --attach
+
+# Ensure daemon + attach
+component-explorer serve -p config.json --background --attach
+
+# Kill running daemon
+component-explorer serve -p config.json --kill
+```
+
+### `mcp`
+
+Start a [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio. Auto-starts a daemon if one is not already running.
+
+```bash
+component-explorer mcp -p <config>
+```
+
+| Option | Description |
+|---|---|
+| `-p, --project, -c <path>` | **(required)** Path to a component-explorer.json config file |
+
+```bash
+component-explorer mcp --project config.json
+```
+
+## Global Options
+
+All commands support `-v` / `--verbose` for increased log output. Use `-vv` for trace-level logging.

package/dist/commands/acceptCommand.d.ts

@@ -4,7 +4,8 @@ export declare class AcceptCommand extends Command {
     static usage: import("clipanion").Usage;
     readonly verbose: number;
     readonly filter: string | undefined;
-    readonly root: string;
+    readonly project: string;
+    readonly screenshotDir: string;
     execute(): Promise<void>;
 }
 //# sourceMappingURL=acceptCommand.d.ts.map

package/dist/commands/acceptCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acceptCommand.d.ts","sourceRoot":"","sources":["../../src/commands/acceptCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,qBAAa,aAAc,SAAQ,OAAO;IACzC,OAAgB,KAAK,aAAgB;IAErC,OAAgB,KAAK,4BAMlB;IAEH,QAAQ,CAAC,OAAO,SAAsG;IACtH,QAAQ,CAAC,MAAM,qBAAkG;IACjH,QAAQ,CAAC,IAAI,SAAqF;IAE5F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA2B9B"}
+{"version":3,"file":"acceptCommand.d.ts","sourceRoot":"","sources":["../../src/commands/acceptCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAM5C,qBAAa,aAAc,SAAQ,OAAO;IACzC,OAAgB,KAAK,aAA2B;IAEhD,OAAgB,KAAK,4BAMlB;IAEH,QAAQ,CAAC,OAAO,SAAsG;IACtH,QAAQ,CAAC,MAAM,qBAAkG;IACjH,QAAQ,CAAC,OAAO,SAAuI;IACvJ,QAAQ,CAAC,aAAa,SAA+F;IAE/G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CA8B9B"}

package/dist/commands/acceptCommand.js

@@ -1,22 +1,28 @@
 import { Command, Option } from 'clipanion';
+import * as path from 'node:path';
 import { ConsoleLogger, verbosityToLogLevel } from '../logger.js';
 import { FileSystemStorage } from '../storage.js';
+import { resolveProject } from '../resolveProject.js';
 
 class AcceptCommand extends Command {
-    static paths = [['accept']];
+    static paths = [['screenshot:accept']];
     static usage = Command.Usage({
-        description: 'Promote current screenshots as baseline',
+        description: 'Promote current screenshots to baseline (file-level only)',
         examples: [
-            ['Accept all', '$0 accept'],
-            ['Accept specific fixtures', '$0 accept --filter "Button/*"'],
+            ['Accept all', '$0 screenshot:accept'],
+            ['Accept specific fixtures', '$0 screenshot:accept --filter "Button/*"'],
         ],
     });
     verbose = Option.Counter('-v,--verbose', 0, { description: 'Increase log verbosity (-v debug, -vv trace)' });
     filter = Option.String('--filter', { required: false, description: 'Filter fixtures by glob pattern' });
-    root = Option.String('--root', process.cwd(), { description: 'Project root directory' });
+    project = Option.String('-p,--project', process.cwd(), { description: 'Project: a directory, vite config file, or component-explorer.json' });
+    screenshotDir = Option.String('--screenshot-dir', '.screenshots', { description: 'Screenshots directory' });
     async execute() {
+        const resolved = await resolveProject(this.project);
+        const projectDir = resolved.projectDir;
         new ConsoleLogger('accept', this.context.stdout, verbosityToLogLevel(this.verbose));
-        const storage = new FileSystemStorage(`${this.root}/.screenshots`);
+        const screenshotPath = path.isAbsolute(this.screenshotDir) ? this.screenshotDir : path.join(projectDir, this.screenshotDir);
+        const storage = new FileSystemStorage(screenshotPath);
         let currentFiles = await storage.list('current');
         if (this.filter) {
             const regex = new RegExp('^current/' + this.filter.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');

package/dist/commands/acceptCommand.js.map

@@ -1 +1 @@
-{"version":3,"file":"acceptCommand.js","sources":["../../src/commands/acceptCommand.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIM,MAAO,aAAc,SAAQ,OAAO,CAAA;IACzC,OAAgB,KAAK,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;AAEpC,IAAA,OAAgB,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;AACrC,QAAA,WAAW,EAAE,yCAAyC;AACtD,QAAA,QAAQ,EAAE;YACT,CAAC,YAAY,EAAE,WAAW,CAAC;YAC3B,CAAC,0BAA0B,EAAE,+BAA+B,CAAC;AAC7D,SAAA;AACD,KAAA,CAAC;AAEO,IAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,8CAA8C,EAAE,CAAC;AAC5G,IAAA,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,iCAAiC,EAAE,CAAC;AACvG,IAAA,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,WAAW,EAAE,wBAAwB,EAAE,CAAC;AAEjG,IAAA,MAAM,OAAO,GAAA;QACI,IAAI,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC;QAClG,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,CAAA,EAAG,IAAI,CAAC,IAAI,CAAA,aAAA,CAAe,CAAC;QAElE,IAAI,YAAY,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;AAEhD,QAAA,IAAI,IAAI,CAAC,MAAM,EAAE;YAChB,MAAM,KAAK,GAAG,IAAI,MAAM,CACvB,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,GAAG,CACxE;AACD,YAAA,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvD;AAEA,QAAA,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE;YAC9B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,CAAC;YAChE;QACD;AAEA,QAAA,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE;YAChC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;YACjD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YACrC,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA,SAAA,EAAY,YAAY,CAAA,CAAE,EAAE,IAAI,CAAC;YACrD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA,IAAA,EAAO,YAAY,CAAA,EAAA,CAAI,CAAC;QACnD;AAEA,QAAA,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA,WAAA,EAAc,YAAY,CAAC,MAAM,CAAA,6BAAA,CAA+B,CAAC;IAC5F;;;;;"}
+{"version":3,"file":"acceptCommand.js","sources":["../../src/commands/acceptCommand.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;AAMM,MAAO,aAAc,SAAQ,OAAO,CAAA;IACzC,OAAgB,KAAK,GAAG,CAAC,CAAC,mBAAmB,CAAC,CAAC;AAE/C,IAAA,OAAgB,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;AACrC,QAAA,WAAW,EAAE,2DAA2D;AACxE,QAAA,QAAQ,EAAE;YACT,CAAC,YAAY,EAAE,sBAAsB,CAAC;YACtC,CAAC,0BAA0B,EAAE,0CAA0C,CAAC;AACxE,SAAA;AACD,KAAA,CAAC;AAEO,IAAA,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,8CAA8C,EAAE,CAAC;AAC5G,IAAA,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,iCAAiC,EAAE,CAAC;AACvG,IAAA,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,WAAW,EAAE,oEAAoE,EAAE,CAAC;AAC7I,IAAA,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,cAAc,EAAE,EAAE,WAAW,EAAE,uBAAuB,EAAE,CAAC;AAEpH,IAAA,MAAM,OAAO,GAAA;QACZ,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;AACnD,QAAA,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU;QACtB,IAAI,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC;AAClG,QAAA,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC;AAC3H,QAAA,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,cAAc,CAAC;QAErD,IAAI,YAAY,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;AAEhD,QAAA,IAAI,IAAI,CAAC,MAAM,EAAE;YAChB,MAAM,KAAK,GAAG,IAAI,MAAM,CACvB,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,GAAG,CACxE;AACD,YAAA,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvD;AAEA,QAAA,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE;YAC9B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,CAAC;YAChE;QACD;AAEA,QAAA,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE;YAChC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;YACjD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YACrC,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA,SAAA,EAAY,YAAY,CAAA,CAAE,EAAE,IAAI,CAAC;YACrD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA,IAAA,EAAO,YAAY,CAAA,EAAA,CAAI,CAAC;QACnD;AAEA,QAAA,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA,WAAA,EAAc,YAAY,CAAC,MAAM,CAAA,6BAAA,CAA+B,CAAC;IAC5F;;;;;"}

package/dist/commands/compareCommand.d.ts

@@ -3,7 +3,11 @@ export declare class CompareCommand extends Command {
     static paths: string[][];
     static usage: import("clipanion").Usage;
     readonly verbose: number;
-    readonly root: string;
+    readonly filter: string | undefined;
+    readonly project: string;
+    readonly baseline: string;
+    readonly current: string;
+    readonly report: string | undefined;
     execute(): Promise<number>;
 }
 //# sourceMappingURL=compareCommand.d.ts.map

package/dist/commands/compareCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compareCommand.d.ts","sourceRoot":"","sources":["../../src/commands/compareCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,qBAAa,cAAe,SAAQ,OAAO;IAC1C,OAAgB,KAAK,aAAiB;IAEtC,OAAgB,KAAK,4BAKlB;IAEH,QAAQ,CAAC,OAAO,SAAsG;IACtH,QAAQ,CAAC,IAAI,SAAqF;IAE5F,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;CAiEhC"}
+{"version":3,"file":"compareCommand.d.ts","sourceRoot":"","sources":["../../src/commands/compareCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAQ5C,qBAAa,cAAe,SAAQ,OAAO;IAC1C,OAAgB,KAAK,aAA4B;IAEjD,OAAgB,KAAK,4BAOlB;IAEH,QAAQ,CAAC,OAAO,SAAsG;IACtH,QAAQ,CAAC,MAAM,qBAAkG;IACjH,QAAQ,CAAC,OAAO,SAAuI;IACvJ,QAAQ,CAAC,QAAQ,SAA2G;IAC5H,QAAQ,CAAC,OAAO,SAAwG;IACxH,QAAQ,CAAC,MAAM,qBAAkJ;IAE3J,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;CA+ChC"}

package/dist/commands/compareCommand.js

@@ -1,89 +1,61 @@
 import { Command, Option } from 'clipanion';
+import * as path from 'node:path';
+import { compareScreenshotsOnDisk, printComparisonToConsole, writeComparisonReport } from '../comparison.js';
 import { ConsoleLogger, verbosityToLogLevel } from '../logger.js';
 import { FileSystemStorage } from '../storage.js';
+import { resolveProject } from '../resolveProject.js';
+import { listPngFiles, matchGlob } from '../utils.js';
 
 class CompareCommand extends Command {
-    static paths = [['compare']];
+    static paths = [['screenshot:compare']];
     static usage = Command.Usage({
-        description: 'Compare current screenshots against baseline',
+        description: 'Compare screenshot directories (file-level only)',
         examples: [
-            ['Compare default directories', '$0 compare'],
+            ['Compare default directories', '$0 screenshot:compare'],
+            ['Compare with custom paths', '$0 screenshot:compare --baseline ./golden --current ./actual'],
+            ['Generate report folder', '$0 screenshot:compare --report ./report'],
         ],
     });
     verbose = Option.Counter('-v,--verbose', 0, { description: 'Increase log verbosity (-v debug, -vv trace)' });
-    root = Option.String('--root', process.cwd(), { description: 'Project root directory' });
+    filter = Option.String('--filter', { required: false, description: 'Filter fixtures by glob pattern' });
+    project = Option.String('-p,--project', process.cwd(), { description: 'Project: a directory, vite config file, or component-explorer.json' });
+    baseline = Option.String('--baseline', '.screenshots/baseline', { description: 'Baseline screenshots directory' });
+    current = Option.String('--current', '.screenshots/current', { description: 'Current screenshots directory' });
+    report = Option.String('--report', { required: false, description: 'Output report folder (contains report.json, report.md, and changed screenshots)' });
     async execute() {
+        const resolved = await resolveProject(this.project);
+        const projectDir = resolved.projectDir;
         new ConsoleLogger('compare', this.context.stdout, verbosityToLogLevel(this.verbose));
-        const storage = new FileSystemStorage(`${this.root}/.screenshots`);
-        const baselineFiles = await storage.list('baseline');
-        const currentFiles = await storage.list('current');
-        const baselineSet = new Set(baselineFiles.map(f => f.replace('baseline/', '')));
-        const currentSet = new Set(currentFiles.map(f => f.replace('current/', '')));
-        const added = [];
-        const removed = [];
-        const changed = [];
-        const unchanged = [];
-        for (const file of currentSet) {
-            if (!baselineSet.has(file)) {
-                added.push(file);
-            }
-            else {
-                const baselineData = await storage.read(`baseline/${file}`);
-                const currentData = await storage.read(`current/${file}`);
-                if (buffersEqual(baselineData, currentData)) {
-                    unchanged.push(file);
-                }
-                else {
-                    changed.push(file);
-                }
-            }
+        const baselineDir = path.isAbsolute(this.baseline) ? this.baseline : path.join(projectDir, this.baseline);
+        const currentDir = path.isAbsolute(this.current) ? this.current : path.join(projectDir, this.current);
+        const baselineStorage = new FileSystemStorage(baselineDir);
+        const currentStorage = new FileSystemStorage(currentDir);
+        // List all PNG files
+        let baselineFiles = await listPngFiles(baselineDir);
+        let currentFiles = await listPngFiles(currentDir);
+        // Apply filter if specified
+        if (this.filter) {
+            const filterFn = (file) => matchGlob(file.replace(/\.png$/, ''), this.filter);
+            baselineFiles = baselineFiles.filter(filterFn);
+            currentFiles = currentFiles.filter(filterFn);
         }
-        for (const file of baselineSet) {
-            if (!currentSet.has(file)) {
-                removed.push(file);
-            }
+        const result = await compareScreenshotsOnDisk({ list: async () => currentFiles, read: (id) => currentStorage.read(id), exists: (id) => currentStorage.exists(id) }, { list: async () => baselineFiles, read: (id) => baselineStorage.read(id), exists: (id) => baselineStorage.exists(id) }, currentFiles, baselineFiles);
+        printComparisonToConsole(result, this.context.stdout);
+        if (this.report) {
+            const reportDir = path.isAbsolute(this.report) ? this.report : path.join(process.cwd(), this.report);
+            await writeComparisonReport({
+                reportDir,
+                result,
+                baselinePath: this.baseline,
+                currentPath: this.current,
+                getBaselineData: (id) => baselineStorage.read(`${id}.png`),
+                getCurrentData: (id) => currentStorage.read(`${id}.png`),
+            });
+            this.context.stdout.write(`\nReport written to: ${this.report}/\n`);
         }
-        if (added.length > 0) {
-            this.context.stdout.write(`Added (${added.length}):\n`);
-            for (const f of added) {
-                this.context.stdout.write(`  + ${f}\n`);
-            }
-        }
-        if (removed.length > 0) {
-            this.context.stdout.write(`Removed (${removed.length}):\n`);
-            for (const f of removed) {
-                this.context.stdout.write(`  - ${f}\n`);
-            }
-        }
-        if (changed.length > 0) {
-            this.context.stdout.write(`Changed (${changed.length}):\n`);
-            for (const f of changed) {
-                this.context.stdout.write(`  ~ ${f}\n`);
-            }
-        }
-        if (unchanged.length > 0) {
-            this.context.stdout.write(`Unchanged (${unchanged.length}):\n`);
-            for (const f of unchanged) {
-                this.context.stdout.write(`  = ${f}\n`);
-            }
-        }
-        const hasDiffs = added.length > 0 || removed.length > 0 || changed.length > 0;
-        if (hasDiffs) {
-            this.context.stdout.write('\nDifferences found.\n');
-            return 1;
-        }
-        this.context.stdout.write('\nNo differences.\n');
-        return 0;
-    }
-}
-function buffersEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] !== b[i])
-            return false;
+        const hasDiffs = result.added.length > 0 || result.removed.length > 0 || result.changed.length > 0;
+        return hasDiffs ? 1 : 0;
     }
-    return true;
 }
 
 export { CompareCommand };

package/dist/commands/compareCommand.js.map

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

package/dist/commands/mcpCommand.d.ts

@@ -2,7 +2,7 @@ import { Command } from 'clipanion';
 export declare class McpCommand extends Command {
     static paths: string[][];
     static usage: import("clipanion").Usage;
-    readonly config: string;
+    readonly project: string;
     execute(): Promise<void>;
 }
 //# sourceMappingURL=mcpCommand.d.ts.map

package/dist/commands/mcpCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpCommand.d.ts","sourceRoot":"","sources":["../../src/commands/mcpCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,qBAAa,UAAW,SAAQ,OAAO;IACtC,OAAgB,KAAK,aAAa;IAElC,OAAgB,KAAK,4BAKlB;IAEH,QAAQ,CAAC,MAAM,SAA8F;IAEvG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ9B"}
+{"version":3,"file":"mcpCommand.d.ts","sourceRoot":"","sources":["../../src/commands/mcpCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAK5C,qBAAa,UAAW,SAAQ,OAAO;IACtC,OAAgB,KAAK,aAAa;IAElC,OAAgB,KAAK,4BAKlB;IAEH,QAAQ,CAAC,OAAO,SAA2I;IAErJ,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAc9B"}

package/dist/commands/mcpCommand.js

@@ -1,19 +1,25 @@
 import { Command, Option } from 'clipanion';
 import { ensureDaemon } from '../daemon/lifecycle.js';
 import { ComponentExplorerMcpServer } from '../mcp/McpServer.js';
+import { resolveProject } from '../resolveProject.js';
 
 class McpCommand extends Command {
     static paths = [['mcp']];
     static usage = Command.Usage({
         description: 'Start an MCP server over stdio. Auto-starts a daemon if not already running.',
         examples: [
-            ['Start MCP server', '$0 mcp -c config.json'],
+            ['Start MCP server', '$0 mcp --project config.json'],
         ],
     });
-    config = Option.String('-c,--config', { required: true, description: 'Path to watch config JSON' });
+    project = Option.String('-p,--project,-c', { required: true, description: 'Project: a directory, vite config file, or component-explorer.json' });
     async execute() {
+        const resolved = await resolveProject(this.project);
+        if (resolved.kind !== 'explorerConfig') {
+            this.context.stderr.write('Error: mcp requires a component-explorer.json config file.\n');
+            return;
+        }
         // Ensure daemon is running (auto-starts in background if needed)
-        const daemon = await ensureDaemon(this.config);
+        const daemon = await ensureDaemon(resolved.configPath);
         // Create and connect the MCP server over stdio
         const mcpServer = new ComponentExplorerMcpServer(daemon);
         await mcpServer.connect();

package/dist/commands/mcpCommand.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcpCommand.js","sources":["../../src/commands/mcpCommand.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIM,MAAO,UAAW,SAAQ,OAAO,CAAA;IACtC,OAAgB,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AAEjC,IAAA,OAAgB,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;AACrC,QAAA,WAAW,EAAE,8EAA8E;AAC3F,QAAA,QAAQ,EAAE;YACT,CAAC,kBAAkB,EAAE,uBAAuB,CAAC;AAC7C,SAAA;AACD,KAAA,CAAC;AAEO,IAAA,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,2BAA2B,EAAE,CAAC;AAE5G,IAAA,MAAM,OAAO,GAAA;;QAEZ,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC;;AAG9C,QAAA,MAAM,SAAS,GAAG,IAAI,0BAA0B,CAAC,MAAM,CAAC;AACxD,QAAA,MAAM,SAAS,CAAC,OAAO,EAAE;IAC1B;;;;;"}
+{"version":3,"file":"mcpCommand.js","sources":["../../src/commands/mcpCommand.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAKM,MAAO,UAAW,SAAQ,OAAO,CAAA;IACtC,OAAgB,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AAEjC,IAAA,OAAgB,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;AACrC,QAAA,WAAW,EAAE,8EAA8E;AAC3F,QAAA,QAAQ,EAAE;YACT,CAAC,kBAAkB,EAAE,8BAA8B,CAAC;AACpD,SAAA;AACD,KAAA,CAAC;AAEO,IAAA,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,oEAAoE,EAAE,CAAC;AAE1J,IAAA,MAAM,OAAO,GAAA;QACZ,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;AACnD,QAAA,IAAI,QAAQ,CAAC,IAAI,KAAK,gBAAgB,EAAE;YACvC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8DAA8D,CAAC;YACzF;QACD;;QAGA,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC;;AAGtD,QAAA,MAAM,SAAS,GAAG,IAAI,0BAA0B,CAAC,MAAM,CAAC;AACxD,QAAA,MAAM,SAAS,CAAC,OAAO,EAAE;IAC1B;;;;;"}

package/dist/commands/screenshotCommand.d.ts

@@ -5,7 +5,12 @@ export declare class ScreenshotCommand extends Command {
     readonly verbose: number;
     readonly filter: string | undefined;
     readonly accept: boolean;
-    readonly root: string;
-    execute(): Promise<void>;
+    readonly project: string;
+    readonly target: string | undefined;
+    readonly compare: boolean;
+    readonly compareTarget: string | undefined;
+    readonly report: string | undefined;
+    execute(): Promise<number>;
+    private _runComparison;
 }
 //# sourceMappingURL=screenshotCommand.d.ts.map

package/dist/commands/screenshotCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshotCommand.d.ts","sourceRoot":"","sources":["../../src/commands/screenshotCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAQ5C,qBAAa,iBAAkB,SAAQ,OAAO;IAC7C,OAAgB,KAAK,aAAoB;IAEzC,OAAgB,KAAK,4BAOlB;IAEH,QAAQ,CAAC,OAAO,SAAsG;IACtH,QAAQ,CAAC,MAAM,qBAAkG;IACjH,QAAQ,CAAC,MAAM,UAAuG;IACtH,QAAQ,CAAC,IAAI,SAAqF;IAE5F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAsC9B"}
+{"version":3,"file":"screenshotCommand.d.ts","sourceRoot":"","sources":["../../src/commands/screenshotCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAW5C,qBAAa,iBAAkB,SAAQ,OAAO;IAC7C,OAAgB,KAAK,aAAoB;IAEzC,OAAgB,KAAK,4BAOlB;IAEH,QAAQ,CAAC,OAAO,SAAsG;IACtH,QAAQ,CAAC,MAAM,qBAAkG;IACjH,QAAQ,CAAC,MAAM,UAAiI;IAChJ,QAAQ,CAAC,OAAO,SAAuI;IACvJ,QAAQ,CAAC,MAAM,qBAAsK;IACrL,QAAQ,CAAC,OAAO,UAA8F;IAC9G,QAAQ,CAAC,aAAa,qBAA+K;IACrM,QAAQ,CAAC,MAAM,qBAA4G;IAErH,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;YAqElB,cAAc;CA+B5B"}

package/dist/commands/screenshotCommand.js

@@ -1,10 +1,13 @@
 import { Command, Option } from 'clipanion';
+import * as path from 'node:path';
 import { PlaywrightBrowserPageFactory } from '../browserPage.js';
+import { compareScreenshotsInMemory, printComparisonToConsole, writeComparisonReport } from '../comparison.js';
 import { BrowserComponentExplorer } from '../componentExplorer.js';
 import { DefaultComponentExplorerHttpServerFactory } from '../httpServer.js';
 import { ConsoleLogger, verbosityToLogLevel } from '../logger.js';
+import { resolveProject, resolvedProjectToViteProjectRef } from '../resolveProject.js';
 import { FileSystemStorage } from '../storage.js';
-import { ViteProjectRef } from '../viteProjectRef.js';
+import { matchGlob } from '../utils.js';
 
 class ScreenshotCommand extends Command {
     static paths = [['screenshot']];
@@ -18,19 +21,39 @@ class ScreenshotCommand extends Command {
     });
     verbose = Option.Counter('-v,--verbose', 0, { description: 'Increase log verbosity (-v debug, -vv trace)' });
     filter = Option.String('--filter', { required: false, description: 'Filter fixtures by glob pattern' });
-    accept = Option.Boolean('--accept', false, { description: 'Write directly to baseline instead of current' });
-    root = Option.String('--root', process.cwd(), { description: 'Project root directory' });
+    accept = Option.Boolean('--accept', false, { description: 'Write to baseline instead of current (mutually exclusive with --target)' });
+    project = Option.String('-p,--project', process.cwd(), { description: 'Project: a directory, vite config file, or component-explorer.json' });
+    target = Option.String('--target', { required: false, description: 'Screenshot output directory (default: .screenshots/current, or .screenshots/baseline with --accept)' });
+    compare = Option.Boolean('--compare', false, { description: 'Compare screenshots after capturing' });
+    compareTarget = Option.String('--compare-target', { required: false, description: 'Directory to compare against (default: .screenshots/baseline, or .screenshots/current with --accept)' });
+    report = Option.String('--report', { required: false, description: 'Output report folder (requires --compare)' });
     async execute() {
+        // Validate mutually exclusive options
+        if (this.accept && this.target) {
+            this.context.stderr.write('Error: --accept and --target are mutually exclusive.\n');
+            return 1;
+        }
         const logger = new ConsoleLogger('screenshot', this.context.stdout, verbosityToLogLevel(this.verbose));
-        const outputDir = this.accept ? 'baseline' : 'current';
-        const storage = new FileSystemStorage(`${this.root}/.screenshots`);
+        const resolved = await resolveProject(this.project);
+        const projectDir = resolved.projectDir;
+        const viteProject = resolvedProjectToViteProjectRef(resolved);
+        // Determine target directory
+        const defaultTarget = this.accept ? '.screenshots/baseline' : '.screenshots/current';
+        const targetDir = this.target ?? defaultTarget;
+        const targetPath = path.isAbsolute(targetDir) ? targetDir : path.join(projectDir, targetDir);
+        // Determine compare target directory
+        const defaultCompareTarget = this.accept ? '.screenshots/current' : '.screenshots/baseline';
+        const compareTargetDir = this.compareTarget ?? defaultCompareTarget;
+        const compareTargetPath = path.isAbsolute(compareTargetDir) ? compareTargetDir : path.join(projectDir, compareTargetDir);
+        const storage = new FileSystemStorage(targetPath);
         const serverFactory = new DefaultComponentExplorerHttpServerFactory();
         const browserFactory = new PlaywrightBrowserPageFactory();
+        const screenshots = new Map();
         let server;
         let explorer;
         try {
             this.context.stdout.write('Starting Vite dev server...\n');
-            server = await serverFactory.createViteServer(ViteProjectRef.fromSourceRootDir(this.root), { logger });
+            server = await serverFactory.createViteServer(viteProject, { logger });
             this.context.stdout.write(`Server running at ${server.url}\n`);
             explorer = new BrowserComponentExplorer(browserFactory, server, logger);
             const fixtures = await explorer.listFixtures();
@@ -39,23 +62,47 @@ class ScreenshotCommand extends Command {
                 : fixtures;
             this.context.stdout.write(`Found ${filtered.length} fixture(s)\n`);
             for (const fixture of filtered) {
-                const png = await explorer.screenshotFixture(fixture.fixtureId);
-                const filePath = `${outputDir}/${fixture.fixtureId}.png`;
-                await storage.write(filePath, png);
+                const result = await explorer.screenshotFixture(fixture.fixtureId);
+                await storage.write(`${fixture.fixtureId}.png`, result.image);
+                screenshots.set(fixture.fixtureId, { data: result.image, background: fixture.background });
                 this.context.stdout.write(`  ✓ ${fixture.fixtureId}\n`);
             }
-            this.context.stdout.write(`\nScreenshots saved to .screenshots/${outputDir}/\n`);
+            this.context.stdout.write(`\nScreenshots saved to ${targetDir}/\n`);
         }
         finally {
             await explorer?.dispose();
             await browserFactory.dispose();
             await server?.dispose();
         }
+        // Compare if requested
+        if (this.compare) {
+            this.context.stdout.write(`\nComparing against ${compareTargetDir}...\n`);
+            return this._runComparison(screenshots, targetPath, compareTargetPath, projectDir);
+        }
+        return 0;
+    }
+    async _runComparison(screenshots, targetPath, compareTargetPath, projectDir) {
+        const compareStorage = new FileSystemStorage(compareTargetPath);
+        const result = await compareScreenshotsInMemory(screenshots, {
+            list: async () => [],
+            read: (id) => compareStorage.read(id),
+            exists: (id) => compareStorage.exists(id),
+        });
+        printComparisonToConsole(result, this.context.stdout);
+        if (this.report) {
+            const reportDir = path.isAbsolute(this.report) ? this.report : path.join(projectDir, this.report);
+            await writeComparisonReport({
+                reportDir,
+                result,
+                baselinePath: compareTargetPath,
+                currentPath: targetPath,
+                getBaselineData: (id) => compareStorage.read(`${id}.png`),
+                getCurrentData: async (id) => screenshots.get(id).data,
+            });
+            this.context.stdout.write(`\nReport written to: ${this.report}/\n`);
+        }
+        return (result.added.length > 0 || result.changed.length > 0) ? 1 : 0;
     }
-}
-function matchGlob(fixtureId, pattern) {
-    const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
-    return regex.test(fixtureId);
 }
 
 export { ScreenshotCommand };