eyeballs-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dane Hesseldahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# eyeballs
+
+Visual monitoring for AI agents and humans. Take screenshots, detect visual changes, track what matters.
+
+Ships as both a **CLI tool** and an **MCP server** in one package.
+
+## Install
+
+```bash
+npm install -g eyeballs
+```
+
+This installs Chromium automatically (~400MB on first install).
+
+## CLI Usage
+
+```bash
+# Take a screenshot
+eyeballs screenshot https://example.com
+eyeballs screenshot https://example.com --viewport 1440x900 -o homepage.png
+
+# Check for visual changes (captures baseline on first run)
+eyeballs check https://example.com
+eyeballs check https://example.com --threshold 10 --region 0,100,1280,500
+
+# Re-check (diffs against baseline)
+eyeballs check https://example.com
+
+# Accept current state as new baseline
+eyeballs check https://example.com --reset
+
+# List watched URLs
+eyeballs list
+
+# Remove a watch
+eyeballs remove <id>
+```
+
+## MCP Server
+
+eyeballs works as an MCP server for AI agents (Claude Desktop, Claude Code, Cursor, etc.).
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "eyeballs": {
+      "command": "eyeballs-mcp"
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add eyeballs eyeballs-mcp
+```
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `screenshot` | Take a screenshot of a URL. Returns the image directly. |
+| `check_url` | Check a URL for visual changes against a stored baseline. |
+| `list_watches` | List all monitored URLs and their status. |
+| `remove_watch` | Remove a watch and its screenshots. |
+
+### Example: screenshot
+
+```
+screenshot({ url: "https://example.com", viewport: { width: 1440, height: 900 } })
+```
+
+Returns the screenshot as an image the agent can see, plus metadata (dimensions, load time).
+
+### Example: check_url
+
+```
+check_url({ url: "https://example.com", threshold: 5, region: { x: 0, y: 100, width: 1280, height: 500 } })
+```
+
+First call captures a baseline. Subsequent calls diff against it and report the percentage of pixels that changed. Use `reset_baseline: true` to accept the current state.
+
+## How It Works
+
+- **Screenshots** via Playwright (headless Chromium)
+- **Diffing** via pixelmatch (deterministic pixel comparison, no AI needed)
+- **Storage** at `~/.eyeballs/` (baselines + screenshots as PNG files)
+- **Threshold** default 5% — configurable per watch to reduce noise from dynamic content
+- **Region crop** — monitor just the part of the page you care about
+
+## Requirements
+
+- Node.js 18+
+- ~400MB disk for Chromium (installed automatically)
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { exec } from 'child_process';
+import { platform } from 'os';
+import { capture, checkUrl, listWatches, removeWatch, shutdownBrowser, EyeballsError, } from './core.js';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+const program = new Command();
+program
+    .name('eyeballs')
+    .description('Visual monitoring for AI agents and humans')
+    .version('0.1.0');
+// --- screenshot ---
+program
+    .command('screenshot')
+    .description('Take a screenshot of a URL')
+    .argument('<url>', 'URL to screenshot')
+    .option('--viewport <size>', 'Viewport size (e.g., 1280x720)', '1280x720')
+    .option('-o, --output <path>', 'Output file path')
+    .option('--no-open', 'Do not open the screenshot after saving')
+    .action(async (url, opts) => {
+    const spinner = ora('Capturing screenshot...').start();
+    try {
+        const [w, h] = opts.viewport.split('x').map(Number);
+        const viewport = { width: w || 1280, height: h || 720 };
+        const result = await capture(url, viewport);
+        const output = opts.output || `screenshot-${Date.now()}.png`;
+        writeFileSync(output, result.buffer);
+        spinner.succeed(`Screenshot saved: ${chalk.cyan(output)} (${result.width}x${result.height}, ${result.loadTimeMs}ms)`);
+        if (opts.open) {
+            openFile(output);
+        }
+    }
+    catch (err) {
+        handleError(spinner, err);
+    }
+    finally {
+        await shutdownBrowser();
+    }
+});
+// --- check ---
+program
+    .command('check')
+    .description('Check a URL for visual changes')
+    .argument('<url>', 'URL to check')
+    .option('--viewport <size>', 'Viewport size (e.g., 1280x720)', '1280x720')
+    .option('--threshold <percent>', 'Diff threshold percentage', '5')
+    .option('--region <coords>', 'Crop region: x,y,width,height')
+    .option('--reset', 'Reset baseline to current state')
+    .action(async (url, opts) => {
+    const spinner = ora('Checking URL...').start();
+    try {
+        const [w, h] = opts.viewport.split('x').map(Number);
+        const viewport = { width: w || 1280, height: h || 720 };
+        const threshold = parseFloat(opts.threshold);
+        let region = undefined;
+        if (opts.region) {
+            const [x, y, rw, rh] = opts.region.split(',').map(Number);
+            region = { x, y, width: rw, height: rh };
+        }
+        const result = await checkUrl({
+            url,
+            viewport,
+            threshold,
+            region,
+            resetBaseline: opts.reset,
+        });
+        if (result.message === 'Baseline captured') {
+            spinner.succeed(`Baseline captured for ${chalk.cyan(url)} (watch ID: ${chalk.yellow(result.watch.id)})`);
+        }
+        else if (result.message === 'Baseline updated') {
+            spinner.succeed(`Baseline updated for ${chalk.cyan(url)}`);
+        }
+        else if (result.changed) {
+            spinner.warn(`${chalk.red('CHANGED')}: ${chalk.cyan(url)} — ${chalk.yellow(result.diffPercent + '%')} pixels differ (threshold: ${result.threshold}%)`);
+        }
+        else {
+            spinner.succeed(`${chalk.green('No change')}: ${chalk.cyan(url)} — ${chalk.dim(result.diffPercent + '%')} pixels differ`);
+        }
+    }
+    catch (err) {
+        handleError(spinner, err);
+    }
+    finally {
+        await shutdownBrowser();
+    }
+});
+// --- list ---
+program
+    .command('list')
+    .description('List watched URLs')
+    .action(() => {
+    const watches = listWatches();
+    if (watches.length === 0) {
+        console.log(chalk.dim('No watches. Run `eyeballs check <url>` to start monitoring.'));
+        return;
+    }
+    console.log(chalk.bold(`\n${watches.length} watch${watches.length === 1 ? '' : 'es'}:\n`));
+    for (const w of watches) {
+        const diffColor = w.lastDiffPercent > (w.config.threshold || 5) ? chalk.red : chalk.green;
+        console.log(`  ${chalk.yellow(w.id)}  ${chalk.cyan(w.url)}`);
+        console.log(`    ${chalk.dim('viewport:')} ${w.viewport.width}x${w.viewport.height}  ${chalk.dim('threshold:')} ${w.config.threshold}%  ${chalk.dim('last diff:')} ${diffColor(w.lastDiffPercent + '%')}`);
+        if (w.lastCheckAt) {
+            console.log(`    ${chalk.dim('last check:')} ${w.lastCheckAt}`);
+        }
+        console.log();
+    }
+});
+// --- remove ---
+program
+    .command('remove')
+    .description('Remove a watch and its screenshots')
+    .argument('<id>', 'Watch ID to remove')
+    .action((id) => {
+    try {
+        removeWatch(id);
+        console.log(chalk.green(`Watch ${id} removed.`));
+    }
+    catch (err) {
+        if (err instanceof EyeballsError) {
+            console.error(chalk.red(`${err.code}: ${err.message}`));
+            process.exit(1);
+        }
+        throw err;
+    }
+});
+// --- helpers ---
+function handleError(spinner, err) {
+    if (err instanceof EyeballsError) {
+        spinner.fail(chalk.red(`${err.code}: ${err.message}`));
+    }
+    else {
+        spinner.fail(chalk.red(err.message));
+    }
+    process.exit(1);
+}
+function openFile(path) {
+    const cmd = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'start' : 'xdg-open';
+    exec(`${cmd} ${JSON.stringify(join(process.cwd(), path))}`);
+}
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,GAAG,MAAM,KAAK,CAAC;AACtB,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAC9B,OAAO,EACL,OAAO,EACP,QAAQ,EACR,WAAW,EACX,WAAW,EACX,eAAe,EACf,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,4CAA4C,CAAC;KACzD,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,qBAAqB;AAErB,OAAO;KACJ,OAAO,CAAC,YAAY,CAAC;KACrB,WAAW,CAAC,4BAA4B,CAAC;KACzC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;KACtC,MAAM,CAAC,mBAAmB,EAAE,gCAAgC,EAAE,UAAU,CAAC;KACzE,MAAM,CAAC,qBAAqB,EAAE,kBAAkB,CAAC;KACjD,MAAM,CAAC,WAAW,EAAE,yCAAyC,CAAC;KAC9D,MAAM,CAAC,KAAK,EAAE,GAAW,EAAE,IAA0D,EAAE,EAAE;IACxF,MAAM,OAAO,GAAG,GAAG,CAAC,yBAAyB,CAAC,CAAC,KAAK,EAAE,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,EAAE,KAAK,EAAE,CAAC,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC;QAExD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAE5C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,cAAc,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC;QAC7D,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO,CAAC,OAAO,CAAC,qBAAqB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,UAAU,KAAK,CAAC,CAAC;QAEtH,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC5B,CAAC;YAAS,CAAC;QACT,MAAM,eAAe,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,gBAAgB;AAEhB,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,gCAAgC,CAAC;KAC7C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;KACjC,MAAM,CAAC,mBAAmB,EAAE,gCAAgC,EAAE,UAAU,CAAC;KACzE,MAAM,CAAC,uBAAuB,EAAE,2BAA2B,EAAE,GAAG,CAAC;KACjE,MAAM,CAAC,mBAAmB,EAAE,+BAA+B,CAAC;KAC5D,MAAM,CAAC,SAAS,EAAE,iCAAiC,CAAC;KACpD,MAAM,CAAC,KAAK,EAAE,GAAW,EAAE,IAA+E,EAAE,EAAE;IAC7G,MAAM,OAAO,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAC,KAAK,EAAE,CAAC;IAC/C,IAAI,CAAC;QACH,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,EAAE,KAAK,EAAE,CAAC,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC;QACxD,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAE7C,IAAI,MAAM,GAAG,SAAS,CAAC;QACvB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1D,MAAM,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QAC3C,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC;YAC5B,GAAG;YACH,QAAQ;YACR,SAAS;YACT,MAAM;YACN,aAAa,EAAE,IAAI,CAAC,KAAK;SAC1B,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,OAAO,KAAK,mBAAmB,EAAE,CAAC;YAC3C,OAAO,CAAC,OAAO,CAAC,yBAAyB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QAC3G,CAAC;aAAM,IAAI,MAAM,CAAC,OAAO,KAAK,kBAAkB,EAAE,CAAC;YACjD,OAAO,CAAC,OAAO,CAAC,wBAAwB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7D,CAAC;aAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CACV,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,GAAG,GAAG,CAAC,8BAA8B,MAAM,CAAC,SAAS,IAAI,CAC1I,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,OAAO,CACb,GAAG,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,GAAG,GAAG,CAAC,gBAAgB,CACzG,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC5B,CAAC;YAAS,CAAC;QACT,MAAM,eAAe,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,eAAe;AAEf,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,mBAAmB,CAAC;KAChC,MAAM,CAAC,GAAG,EAAE;IACX,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAE9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC,CAAC;QACtF,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,MAAM,SAAS,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC;IAC3F,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;QAC1F,OAAO,CAAC,GAAG,CACT,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAChD,CAAC;QACF,OAAO,CAAC,GAAG,CACT,OAAO,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,eAAe,GAAG,GAAG,CAAC,EAAE,CAC9L,CAAC;QACF,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;YAClB,OAAO,CAAC,GAAG,CAAC,OAAO,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,iBAAiB;AAEjB,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,oCAAoC,CAAC;KACjD,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;KACtC,MAAM,CAAC,CAAC,EAAU,EAAE,EAAE;IACrB,IAAI,CAAC;QACH,WAAW,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,kBAAkB;AAElB,SAAS,WAAW,CAAC,OAA+B,EAAE,GAAY;IAChE,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;QACjC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,GAAG,GAAG,QAAQ,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IAC7F,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,67 @@
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface Region {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface CaptureResult {
+    buffer: Buffer;
+    width: number;
+    height: number;
+    loadTimeMs: number;
+}
+export interface DiffResult {
+    changed: boolean;
+    diffPercent: number;
+    threshold: number;
+    diffBuffer?: Buffer;
+}
+export interface Watch {
+    id: string;
+    url: string;
+    viewport: Viewport;
+    mode: 'pixel';
+    config: {
+        threshold: number;
+        region: Region | null;
+    };
+    baselinePath: string;
+    createdAt: string;
+    lastCheckAt: string | null;
+    lastDiffPercent: number;
+}
+export interface WatchesFile {
+    watches: Watch[];
+}
+export interface CheckResult {
+    changed: boolean;
+    diffPercent: number;
+    threshold: number;
+    message: string;
+    screenshotBuffer: Buffer;
+    diffBuffer?: Buffer;
+    watch: Watch;
+}
+export type EyeballsErrorCode = 'TIMEOUT' | 'LOAD_FAILED' | 'INVALID_URL' | 'BROWSER_NOT_INSTALLED' | 'BROWSER_VERSION_MISMATCH' | 'BROWSER_LAUNCH_FAILED' | 'STORAGE_FAILED' | 'NOT_FOUND';
+export declare class EyeballsError extends Error {
+    code: EyeballsErrorCode;
+    constructor(code: EyeballsErrorCode, message: string);
+}
+export declare function loadWatches(): WatchesFile;
+export declare function shutdownBrowser(): Promise<void>;
+export declare function capture(url: string, viewport?: Viewport): Promise<CaptureResult>;
+export declare function diff(baseline: Buffer, current: Buffer, threshold?: number, region?: Region | null): DiffResult;
+export declare function checkUrl(options: {
+    url: string;
+    viewport?: Viewport;
+    threshold?: number;
+    region?: Region | null;
+    resetBaseline?: boolean;
+}): Promise<CheckResult>;
+export declare function listWatches(): Watch[];
+export declare function removeWatch(id: string): void;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE;QACN,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;IACF,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;CACd;AAID,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,aAAa,GACb,aAAa,GACb,uBAAuB,GACvB,0BAA0B,GAC1B,uBAAuB,GACvB,gBAAgB,GAChB,WAAW,CAAC;AAEhB,qBAAa,aAAc,SAAQ,KAAK;IAE7B,IAAI,EAAE,iBAAiB;gBAAvB,IAAI,EAAE,iBAAiB,EAC9B,OAAO,EAAE,MAAM;CAKlB;AAiBD,wBAAgB,WAAW,IAAI,WAAW,CAWzC;AAoDD,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAKrD;AA8BD,wBAAsB,OAAO,CAC3B,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,QAAuC,GAChD,OAAO,CAAC,aAAa,CAAC,CA4CxB;AAID,wBAAgB,IAAI,CAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAU,EACrB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,UAAU,CA0CZ;AAmBD,wBAAsB,QAAQ,CAAC,OAAO,EAAE;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAAC,WAAW,CAAC,CAoFvB;AAID,wBAAgB,WAAW,IAAI,KAAK,EAAE,CAErC;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAsB5C"}

package/dist/core.js

@@ -0,0 +1,301 @@
+import { chromium } from 'playwright';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { randomUUID } from 'crypto';
+export class EyeballsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'EyeballsError';
+    }
+}
+// --- Storage ---
+const EYEBALLS_DIR = join(homedir(), '.eyeballs');
+const SCREENSHOTS_DIR = join(EYEBALLS_DIR, 'screenshots');
+const WATCHES_FILE = join(EYEBALLS_DIR, 'watches.json');
+function ensureDirs() {
+    try {
+        mkdirSync(EYEBALLS_DIR, { recursive: true });
+        mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+    }
+    catch {
+        throw new EyeballsError('STORAGE_FAILED', 'Could not create ~/.eyeballs directory');
+    }
+}
+export function loadWatches() {
+    ensureDirs();
+    if (!existsSync(WATCHES_FILE)) {
+        return { watches: [] };
+    }
+    try {
+        const raw = readFileSync(WATCHES_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { watches: [] };
+    }
+}
+function saveWatches(data) {
+    ensureDirs();
+    try {
+        writeFileSync(WATCHES_FILE, JSON.stringify(data, null, 2));
+    }
+    catch {
+        throw new EyeballsError('STORAGE_FAILED', 'Could not write watches.json');
+    }
+}
+function saveScreenshot(id, suffix, buffer) {
+    ensureDirs();
+    const filename = `${id}-${suffix}.png`;
+    const filepath = join(SCREENSHOTS_DIR, filename);
+    try {
+        writeFileSync(filepath, buffer);
+    }
+    catch {
+        throw new EyeballsError('STORAGE_FAILED', 'Could not write screenshot');
+    }
+    return filepath;
+}
+// --- Browser ---
+let browser = null;
+async function getBrowser() {
+    if (browser && browser.isConnected()) {
+        return browser;
+    }
+    try {
+        browser = await chromium.launch();
+        return browser;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Executable doesn\'t exist') || msg.includes('browserType.launch')) {
+            if (msg.includes('Chromium') && msg.includes('revision')) {
+                throw new EyeballsError('BROWSER_VERSION_MISMATCH', 'Chromium version mismatch. Run: npx playwright install chromium');
+            }
+            throw new EyeballsError('BROWSER_NOT_INSTALLED', 'Run: npx playwright install chromium');
+        }
+        throw new EyeballsError('BROWSER_LAUNCH_FAILED', `Chromium cannot start: ${msg}`);
+    }
+}
+export async function shutdownBrowser() {
+    if (browser) {
+        await browser.close().catch(() => { });
+        browser = null;
+    }
+}
+// Cleanup on exit
+process.on('exit', () => {
+    browser?.close().catch(() => { });
+});
+process.on('SIGINT', async () => {
+    await shutdownBrowser();
+    process.exit(0);
+});
+process.on('SIGTERM', async () => {
+    await shutdownBrowser();
+    process.exit(0);
+});
+// --- URL validation ---
+function validateUrl(url) {
+    if (!url.startsWith('http://') && !url.startsWith('https://')) {
+        throw new EyeballsError('INVALID_URL', 'URL must start with http:// or https://');
+    }
+    try {
+        new URL(url);
+    }
+    catch {
+        throw new EyeballsError('INVALID_URL', `Invalid URL: ${url}`);
+    }
+}
+// --- Capture ---
+export async function capture(url, viewport = { width: 1280, height: 720 }) {
+    validateUrl(url);
+    const b = await getBrowser();
+    const context = await b.newContext({ viewport });
+    const page = await context.newPage();
+    const start = Date.now();
+    try {
+        const response = await page.goto(url, {
+            waitUntil: 'networkidle',
+            timeout: 30000,
+        });
+        if (response) {
+            const status = response.status();
+            if (status >= 400) {
+                throw new EyeballsError('LOAD_FAILED', `Page returned ${status}`);
+            }
+        }
+        // Wait for paint to settle
+        await page.waitForTimeout(2000);
+        const buffer = await page.screenshot({ type: 'png' });
+        const loadTimeMs = Date.now() - start;
+        return {
+            buffer: Buffer.from(buffer),
+            width: viewport.width,
+            height: viewport.height,
+            loadTimeMs,
+        };
+    }
+    catch (err) {
+        if (err instanceof EyeballsError)
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Timeout') || msg.includes('timeout')) {
+            throw new EyeballsError('TIMEOUT', 'Page failed to load within 30s');
+        }
+        throw new EyeballsError('LOAD_FAILED', `Failed to load page: ${msg}`);
+    }
+    finally {
+        await page.close().catch(() => { });
+        await context.close().catch(() => { });
+    }
+}
+// --- Diff ---
+export function diff(baseline, current, threshold = 5, region) {
+    let img1 = PNG.sync.read(baseline);
+    let img2 = PNG.sync.read(current);
+    // Region crop if specified
+    if (region) {
+        img1 = cropPng(img1, region);
+        img2 = cropPng(img2, region);
+    }
+    // Ensure same dimensions
+    if (img1.width !== img2.width || img1.height !== img2.height) {
+        return {
+            changed: true,
+            diffPercent: 100,
+            threshold,
+            diffBuffer: undefined,
+        };
+    }
+    const { width, height } = img1;
+    const diffPng = new PNG({ width, height });
+    const numDiffPixels = pixelmatch(img1.data, img2.data, diffPng.data, width, height, { threshold: 0.1 });
+    const totalPixels = width * height;
+    const diffPercent = (numDiffPixels / totalPixels) * 100;
+    const changed = diffPercent > threshold;
+    return {
+        changed,
+        diffPercent: Math.round(diffPercent * 100) / 100,
+        threshold,
+        diffBuffer: changed ? Buffer.from(PNG.sync.write(diffPng)) : undefined,
+    };
+}
+function cropPng(png, region) {
+    const cropped = new PNG({ width: region.width, height: region.height });
+    for (let y = 0; y < region.height; y++) {
+        for (let x = 0; x < region.width; x++) {
+            const srcIdx = ((region.y + y) * png.width + (region.x + x)) << 2;
+            const dstIdx = (y * region.width + x) << 2;
+            cropped.data[dstIdx] = png.data[srcIdx];
+            cropped.data[dstIdx + 1] = png.data[srcIdx + 1];
+            cropped.data[dstIdx + 2] = png.data[srcIdx + 2];
+            cropped.data[dstIdx + 3] = png.data[srcIdx + 3];
+        }
+    }
+    return cropped;
+}
+// --- Check URL (baseline + diff) ---
+export async function checkUrl(options) {
+    const { url, viewport = { width: 1280, height: 720 }, threshold = 5, region = null, resetBaseline = false } = options;
+    const data = loadWatches();
+    let watch = data.watches.find((w) => w.url === url);
+    // Capture current screenshot
+    const result = await capture(url, viewport);
+    // Reset baseline
+    if (watch && resetBaseline) {
+        const baselinePath = saveScreenshot(watch.id, 'baseline', result.buffer);
+        watch.baselinePath = baselinePath;
+        watch.viewport = viewport;
+        watch.config = { threshold, region };
+        watch.lastCheckAt = new Date().toISOString();
+        watch.lastDiffPercent = 0;
+        saveWatches(data);
+        return {
+            changed: false,
+            diffPercent: 0,
+            threshold,
+            message: 'Baseline updated',
+            screenshotBuffer: result.buffer,
+            watch,
+        };
+    }
+    // No baseline yet, store it
+    if (!watch) {
+        const id = randomUUID().slice(0, 8);
+        const baselinePath = saveScreenshot(id, 'baseline', result.buffer);
+        watch = {
+            id,
+            url,
+            viewport,
+            mode: 'pixel',
+            config: { threshold, region },
+            baselinePath,
+            createdAt: new Date().toISOString(),
+            lastCheckAt: new Date().toISOString(),
+            lastDiffPercent: 0,
+        };
+        data.watches.push(watch);
+        saveWatches(data);
+        return {
+            changed: false,
+            diffPercent: 0,
+            threshold,
+            message: 'Baseline captured',
+            screenshotBuffer: result.buffer,
+            watch,
+        };
+    }
+    // Diff against baseline
+    const baseline = readFileSync(watch.baselinePath);
+    const diffResult = diff(baseline, result.buffer, threshold, region);
+    // Save current screenshot
+    saveScreenshot(watch.id, 'latest', result.buffer);
+    if (diffResult.diffBuffer) {
+        saveScreenshot(watch.id, 'diff', diffResult.diffBuffer);
+    }
+    watch.lastCheckAt = new Date().toISOString();
+    watch.lastDiffPercent = diffResult.diffPercent;
+    saveWatches(data);
+    return {
+        changed: diffResult.changed,
+        diffPercent: diffResult.diffPercent,
+        threshold,
+        message: diffResult.changed
+            ? `Changed: ${diffResult.diffPercent}% pixels differ (threshold: ${threshold}%)`
+            : `No change: ${diffResult.diffPercent}% pixels differ (threshold: ${threshold}%)`,
+        screenshotBuffer: result.buffer,
+        diffBuffer: diffResult.diffBuffer,
+        watch,
+    };
+}
+// --- List / Remove watches ---
+export function listWatches() {
+    return loadWatches().watches;
+}
+export function removeWatch(id) {
+    const data = loadWatches();
+    const idx = data.watches.findIndex((w) => w.id === id);
+    if (idx === -1) {
+        throw new EyeballsError('NOT_FOUND', `Watch ${id} not found`);
+    }
+    data.watches.splice(idx, 1);
+    saveWatches(data);
+    // Clean up screenshot files for this watch
+    try {
+        const files = readdirSync(SCREENSHOTS_DIR);
+        for (const file of files) {
+            if (file.startsWith(`${id}-`)) {
+                unlinkSync(join(SCREENSHOTS_DIR, file));
+            }
+        }
+    }
+    catch {
+        // Best effort cleanup
+    }
+}
+//# sourceMappingURL=core.js.map