@kaze-no-ryuu/argus 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaze
+
+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

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# Argus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Does what you built match the real thing?** Argus compares your local site, page by page and at desktop, tablet and mobile sizes, against a **live reference site** and/or **design images**. It tells you how much changed and *which element* changed.
+
+```bash
+npx @kaze-no-ryuu/argus
+```
+
+That's the whole setup. The first run downloads Chromium if it isn't installed yet, detects your framework, writes a config and adds an `argus` npm script. Every run after that starts your dev server, screenshots everything, diffs it and writes one HTML report.
+
+## Why Argus
+
+- **Zero-config start.** Detects Next.js, Astro, Nuxt, SvelteKit, Vite and others, the dev command and port, and every route. No test files to write.
+- **Compares against a live site *and* designs in one run.** Rebuilding or migrating a site? Point it at production. Building from mockups? Drop PNGs in `designs/`. Mix both per page and per viewport.
+- **Says where, not just how much.** Each changed area is labeled with the elements it falls in (`section#pricing`, `h2 "Plans"`), so you can jump straight to the code.
+- **Catches layout shifts.** A page that got taller or shorter (missing or extra content) is flagged on its own, with the height difference. A pixel diff alone hides this.
+- **Built for AI agents and CI.** `--json` output with absolute file paths, `failed` flags and element labels, plus clear exit codes (`0` / `1` / `2`). An agent can run → read → fix → re-run with no human in the loop.
+- **Runs your dev server for you.** Starts it, waits until it responds, and stops it afterwards. If it's already running, it's reused.
+- **One self-contained report.** A pass/fail grid, % per page × viewport, the list of changed areas, and a diff / reference / local / side-by-side viewer. Works in light and dark mode.
+- **Fast and safe to run in parallel.** Parallel tabs sized to your CPU and memory, CI sharding, remote browsers, and a lock so parallel runs can't overwrite each other.
+
+### Compared to alternatives
+
+| | Argus | BackstopJS | Playwright `toHaveScreenshot` | Percy / Chromatic / Applitools |
+|---|:-:|:-:|:-:|:-:|
+| Live site vs local (no stored screenshots) | ✓ | ✓ | — | — |
+| Design images as reference | ✓ | manual | — | — |
+| Detects framework, routes, dev server | ✓ | — | — | — |
+| Names the changed elements | ✓ | — | — | — |
+| JSON made for agents | ✓ | — | — | API |
+| Review dashboard / approval flow | — | — | — | ✓ |
+| Self-hosted, free | ✓ | ✓ | ✓ | — |
+
+Use the hosted services when you need a team review flow for screenshots that change over time. Use Argus when the question is "does my build match *that*?"
+
+## Quick start
+
+```bash
+npm i -D @kaze-no-ryuu/argus      # pin the version in your project (optional, recommended for CI)
+npx argus init                    # detects your framework, writes argus.config.json, adds an npm script
+npm run argus                     # first run downloads Chromium (~100 MB, once)
+```
+
+On a fresh Linux machine or CI image, Chromium also needs system libraries. Install them once with `npx playwright install-deps chromium` (needs root).
+
+Running `npx argus` without a config does the `init` step for you.
+
+> The npm package is `@kaze-no-ryuu/argus` and the command is `argus`. Without a local install, run `npx @kaze-no-ryuu/argus` instead. `npx argus` would fetch an unrelated package.
+
+`init` detects:
+
+| | |
+|---|---|
+| Framework | Next.js, Astro, Nuxt, SvelteKit, Gatsby, Remix, React Router, Angular, CRA, Vue CLI, Eleventy, Vite, plain HTML |
+| Start command | the `dev` / `start` / `serve` / `preview` script, using your package manager (npm, pnpm, yarn, bun) |
+| Local URL | the framework's default port, or a `--port` / `-p` in the script |
+| Pages | routes from `pages/`, `app/`, `src/pages/`, `src/routes/`, or `*.html` files (dynamic `[slug]` routes are skipped) |
+| Remote URL | `homepage` in package.json, `site:` in the framework config, or `CNAME`. Otherwise it asks, or takes `--remote URL` |
+
+## Config: `argus.config.json`
+
+```json
+{
+  "remote": "https://www.example.com",
+  "local": { "url": "http://localhost:4321", "command": "npm run dev" },
+  "pages": [
+    "/",
+    "/about",
+    { "path": "/pricing", "local": "/pricing.html" },
+    { "path": "/contact", "ref": { "desktop": "mockups/contact.png" } }
+  ],
+  "refs": "designs/{page}-{viewport}.png",
+  "viewports": {
+    "desktop": { "width": 1440, "height": 900 },
+    "tablet":  { "width": 768,  "height": 1024, "isMobile": true },
+    "mobile":  { "width": 390,  "height": 844,  "isMobile": true }
+  },
+  "threshold": 0.1,
+  "imageThreshold": 1,
+  "out": "argus",
+  "diffDir": "argus/diffs",
+  "report": "argus/report.html",
+  "css": ".reveal{opacity:1!important;transform:none!important}"
+}
+```
+
+| key | meaning |
+|---|---|
+| `remote` | Reference site. Each page path is appended to it. Optional if every page has a reference image. |
+| `refs` | Path pattern for reference images (PNG). Wherever a matching file exists, it is used instead of the remote screenshot. `{page}` is the page name (`index`, `about`, `blog-post`), `{viewport}` the viewport key. |
+| `pages[].ref` | Reference image for one page: `"x.png"` for all viewports, or `{ "mobile": "x.png" }`. Takes priority over `refs`. |
+| `local.url` / `local.command` | If `url` already responds, that server is used. Otherwise `command` is started, awaited, and stopped afterwards (its output goes to `<out>/server.log`). |
+| `pages` | Paths, or `{ path, remote, local, name }` when the two sites use different URLs (relative paths or full URLs). |
+| `viewports` | Any number of them. Optional: `deviceScaleFactor` (default 1), `isMobile`, `userAgent`. |
+| `threshold` | Max % of changed pixels per page and viewport before it fails. |
+| `imageThreshold` | Same, for checks against reference images (defaults to `threshold`). Design tools draw text slightly differently from browsers, so a looser value is common. |
+| `out` / `diffDir` / `report` | Where screenshots, diff images and the HTML report go. |
+| `css` | Injected into both sites before the screenshot, e.g. to finish scroll animations or hide cookie banners. |
+| `settle`, `serverTimeout`, `concurrency` | Wait (ms) before each screenshot (default 300), time to wait for the dev server to start (default 120000), number of parallel tabs. |
+
+Before each screenshot, the page is scrolled from top to bottom so scroll-triggered animations play.
+
+## Comparing against design images
+
+Export each frame as PNG at 1×, name it `<page>-<viewport>.png` and put it in `designs/` (e.g. `designs/index-desktop.png`, `designs/about-mobile.png`). Pages or viewports without an image still compare against `remote`.
+
+- The image width must equal the viewport width × `deviceScaleFactor`. A 375px mobile frame needs `"mobile": { "width": 375, … }`. If the width is wrong, that check shows an error explaining it.
+- A height difference is only a **warning** for images, because design frames rarely match the real page height. The pixel diff and changed areas are still reported.
+
+## Output
+
+```
+argus/
+  report.html                  one-page report: pass/fail matrix, % per page × viewport, changed areas, image viewer
+  desktop/about-remote.png     screenshots
+  desktop/about-local.png
+  diffs/desktop/about.png      changed pixels in red
+```
+
+A check **fails** when it changed more than the threshold, when the page size differs from the remote screenshot (missing or extra content), or when it errors (HTTP ≥ 400, timeout, missing or wrong-width image). Each result has `"failed": true/false` and `"refType": "remote" | "image"`.
+
+## CLI
+
+```
+argus init [--remote URL] [--force] [-y]
+argus [-c config] [-p /about,/faq] [--viewport mobile] [--json] [--open]
+          [--no-server] [--no-shoot] [-j N] [--shard k/n] [--browser-ws URL]
+```
+
+Exit codes: `0` everything within the threshold, `1` diffs found, `2` error.
+
+## For AI agents
+
+```bash
+npx argus --json
+```
+
+```json
+{
+  "ok": false, "threshold": 0.1, "report": "/abs/argus/report.html",
+  "counts": { "total": 6, "passed": 4, "failed": 2, "errors": 0 },
+  "failed": ["about@mobile", "about@desktop"],
+  "results": [{
+    "page": "about", "viewport": "mobile", "status": "diff",
+    "diffPercentage": 3.42, "diffCount": 11873, "sizeMismatch": true,
+    "size": { "remote": { "width": 390, "height": 2400 }, "local": { "width": 390, "height": 2520 } },
+    "bands": [{ "y1": 812, "y2": 1104, "height": 293, "where": ["section#pricing", "h2 \"Plans\""] }],
+    "refType": "remote", "failed": true,
+    "remote": "…/mobile/about-remote.png", "local": "…/mobile/about-local.png", "diff": "…/diffs/mobile/about.png"
+  }]
+}
+```
+
+A fix loop that works well:
+
+1. Go through `failed` and start with `sizeMismatch` entries. A different height means content is missing or extra, which shifts everything below it. Fix those first.
+2. Use `bands[].where` to find the element in your code, and open the `diff` PNG next to the `remote` and `local` PNGs to see what changed.
+3. Re-run only what you touched: `npx argus --json -p /about --viewport mobile`.
+
+## Scaling
+
+- `-j N` sets how many tabs run at once. By default it's picked from your CPU and memory (container limits included).
+- `--shard k/n` splits the checks across CI jobs. Give each shard its own `out`.
+- `--browser-ws ws://…` uses a remote browser (`npx playwright run-server`, Browserless).
+- Runs that share an `out` folder wait for each other through a lock file instead of overwriting each other's files.
+
+## API
+
+```js
+import { loadConfig, run } from '@kaze-no-ryuu/argus';
+const result = await run(loadConfig('argus.config.json'), { viewports: ['mobile'] });
+```
+
+`detect(cwd)` and `init(opts)` are exported from `@kaze-no-ryuu/argus/init`. TypeScript types are included (`Config`, `RawConfig`, `Result`, `Summary`, …).
+
+## Development
+
+Requires Node 22.18 or newer. The tests run the TypeScript source directly.
+
+```bash
+npm install && npx playwright install chromium
+npm run typecheck   # tsc, source and tests
+npm test            # unit, init/detection, CLI and end-to-end (real browser) tests
+npm run test:coverage
+npm run build       # src/ → dist/
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readFileSync, existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { run, loadConfig, CONFIG_FILE } from './index.js';
+import { init } from './init.js';
+import { fmtPct } from './report.js';
+const { values: a, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        config: { type: 'string', short: 'c', default: CONFIG_FILE },
+        remote: { type: 'string' },
+        force: { type: 'boolean' },
+        yes: { type: 'boolean', short: 'y' },
+        only: { type: 'string', short: 'p' },
+        viewport: { type: 'string' },
+        concurrency: { type: 'string', short: 'j' },
+        shard: { type: 'string' },
+        'browser-ws': { type: 'string' },
+        'no-shoot': { type: 'boolean' },
+        'no-server': { type: 'boolean' },
+        open: { type: 'boolean' },
+        json: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+    },
+});
+if (a.version) {
+    console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+    process.exit(0);
+}
+if (a.help) {
+    console.log(`argus: compare your local site with a live site or design images, page by page, per viewport
+
+  argus init [--remote URL] [--force] [-y]   detect framework, write ${CONFIG_FILE},
+                                                 add "argus" npm script
+  argus [options]                            start dev server, screenshot local and the
+                                                 reference (remote site or design PNGs),
+                                                 diff, write HTML report
+
+  -c, --config FILE   config file (default ${CONFIG_FILE}; created by init if missing)
+  -p, --only a,b      only these pages (name or path)
+  --viewport a,b      only these viewports (e.g. mobile)
+  -j, --concurrency N parallel tabs (default: auto from CPU/memory)
+  --shard k/n         run every n-th check starting at k (CI matrix)
+  --browser-ws URL    use a remote browser (Playwright server / Browserless)
+  --no-server         don't start local.command; expect local.url to be up
+  --no-shoot          re-diff existing screenshots only
+  --open              open the HTML report when done
+  --json              machine-readable result on stdout
+  -y, --yes           init: never prompt
+  -v, --version       print version
+
+Exit codes: 0 all checks within threshold, 1 diffs found, 2 error.`);
+    process.exit(0);
+}
+const log = a.json ? () => { } : (m) => console.error(m);
+const list = (s) => s?.split(',').map((x) => x.trim()).filter(Boolean);
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+try {
+    if (positionals[0] === 'init') {
+        const res = await init({ remote: a.remote, force: a.force, yes: a.yes || a.json, log });
+        if (a.json)
+            console.log(JSON.stringify(res, null, 2));
+        process.exit(0);
+    }
+    if (positionals.length)
+        throw new Error(`unknown command "${positionals[0]}" (see --help)`);
+    if (!existsSync(a.config)) {
+        log(`no ${a.config} found, running init`);
+        const res = await init({ remote: a.remote, yes: a.yes || a.json, log });
+        if (res.needsRemote)
+            throw new Error(`set "remote" in ${CONFIG_FILE} (or put reference PNGs in designs/ and remove "remote"), then run argus again`);
+    }
+    const cfg = loadConfig(a.config);
+    if (a.remote)
+        cfg.remote = a.remote;
+    const res = await run(cfg, {
+        log,
+        shoot: !a['no-shoot'],
+        server: !a['no-server'],
+        only: list(a.only),
+        viewports: list(a.viewport),
+        concurrency: a.concurrency ? Number(a.concurrency) : undefined,
+        shard: a.shard,
+        browserWs: a['browser-ws'],
+    });
+    if (a.json) {
+        console.log(JSON.stringify(res, null, 2));
+    }
+    else {
+        console.log(`\n${'Page'.padEnd(20)}${'Viewport'.padEnd(10)}${'Diff'.padEnd(10)}Where`);
+        console.log('-'.repeat(70));
+        for (const r of res.results) {
+            const d = r.status === 'error' ? 'ERROR' : fmtPct(r.diffPercentage ?? 0);
+            const where = r.status === 'error' ? r.error
+                : [r.sizeMismatch && `height ${r.size?.remote.height}→${r.size?.local.height}`, r.bands?.[0]?.where[0]].filter(Boolean).join(', ');
+            console.log(`${r.page.padEnd(20)}${r.viewport.padEnd(10)}${d.padEnd(10)}${where}`);
+        }
+        console.log(`\n${res.ok ? 'OK' : `FAILED: ${res.failed.join(', ')}`}\nReport: ${res.report}`);
+    }
+    if (a.open) {
+        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open';
+        spawn(cmd, [res.report], { stdio: 'ignore', detached: true }).unref();
+    }
+    process.exit(res.ok ? 0 : 1);
+}
+catch (e) {
+    if (a.json)
+        console.log(JSON.stringify({ ok: false, error: errMsg(e) }));
+    else
+        console.error(`error: ${errMsg(e)}`);
+    process.exit(2);
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { type Browser } from 'playwright';
+import type { Band, Box, Config, Log, Page, RawConfig, Result, RunOptions, Summary, Viewport } from './types.ts';
+export type * from './types.ts';
+export declare const CONFIG_FILE = "argus.config.json";
+export declare const DEFAULTS: {
+    out: string;
+    threshold: number;
+    viewports: Record<string, Viewport>;
+    css: string;
+    settle: number;
+    serverTimeout: number;
+};
+export declare const isMissingBrowser: (e: unknown) => boolean;
+export declare function launchBrowser(log: Log): Promise<Browser>;
+export declare function loadConfig(file?: string): Config;
+export declare function normalizeConfig(raw: RawConfig, root?: string): Config;
+export declare function pageName(p: string): string;
+export declare function resolvePages(cfg: Config): Page[];
+export declare function autoConcurrency(): number;
+export interface ServerOptions {
+    url: string;
+    command?: string | null;
+    cwd: string;
+    timeout: number;
+    logFile: string;
+    log: Log;
+}
+export declare function startServer({ url, command, cwd, timeout, logFile, log }: ServerOptions): Promise<() => void>;
+export declare function toBands(lines: number[], boxes: Box[], gap?: number, max?: number): Band[];
+export declare function refImage(page: Pick<Page, 'name' | 'ref'>, vp: string, cfg: Pick<Config, 'root' | 'refs'>): string | null;
+export declare function isFailed(r: Result, cfg: Pick<Config, 'threshold' | 'imageThreshold'>): boolean;
+export declare function run(cfg: Config, opts?: RunOptions): Promise<Summary>;

package/dist/index.js

@@ -0,0 +1,462 @@
+import { chromium } from 'playwright';
+import { compare } from 'odiff-bin';
+import { spawn, execSync, execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import { setTimeout as sleep } from 'node:timers/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { writeReport } from './report.js';
+export const CONFIG_FILE = 'argus.config.json';
+export const DEFAULTS = {
+    out: 'argus',
+    threshold: 0.1,
+    viewports: {
+        desktop: { width: 1440, height: 900 },
+        tablet: { width: 768, height: 1024, isMobile: true },
+        mobile: { width: 390, height: 844, isMobile: true },
+    },
+    css: '.reveal{opacity:1!important;transform:none!important;transition:none!important}',
+    settle: 300,
+    serverTimeout: 120000,
+};
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+export const isMissingBrowser = (e) => /Executable doesn't exist/.test(errMsg(e));
+// Launches Chromium, downloading it first if it isn't installed yet, so
+// `npx argus` works without a separate `playwright install` step.
+export async function launchBrowser(log) {
+    try {
+        return await chromium.launch();
+    }
+    catch (e) {
+        if (!isMissingBrowser(e))
+            throw e;
+        log('Chromium is not installed yet, downloading it (one time, ~100 MB)...');
+        const cli = path.join(path.dirname(createRequire(import.meta.url).resolve('playwright')), 'cli.js');
+        // Output goes to stderr so --json stdout stays clean.
+        execFileSync(process.execPath, [cli, 'install', 'chromium'], { stdio: ['ignore', 2, 2] });
+        return chromium.launch();
+    }
+}
+// Fills defaults and resolves file paths relative to the config file.
+export function loadConfig(file = CONFIG_FILE) {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return normalizeConfig(raw, path.dirname(path.resolve(file)));
+}
+export function normalizeConfig(raw, root = process.cwd()) {
+    const merged = { ...DEFAULTS, ...raw, root };
+    if (!merged.remote && !merged.refs && !merged.pages?.some((p) => typeof p !== 'string' && p.ref)) {
+        throw new Error('config: set "remote" (reference site URL), "refs" (reference image pattern) or per-page "ref"');
+    }
+    if (!merged.local?.url)
+        throw new Error('config: "local.url" is required');
+    if (!merged.pages?.length)
+        throw new Error('config: "pages" is empty');
+    const out = path.resolve(root, merged.out);
+    return {
+        ...merged,
+        out,
+        diffDir: path.resolve(root, raw.diffDir ?? path.join(out, 'diffs')),
+        report: path.resolve(root, raw.report ?? path.join(out, 'report.html')),
+    };
+}
+export function pageName(p) {
+    const slug = p.replace(/\.html?$/, '').replace(/^\/+|\/+$/g, '').replace(/[^\w.-]+/g, '-');
+    return slug || 'index';
+}
+const join = (base, p) => base.replace(/\/+$/, '') + (p.startsWith('/') ? p : `/${p}`);
+// Pages are paths ("/about") or { path, remote, local, name, ref } when the
+// two sites use different URLs, or the reference is an image instead of a site.
+export function resolvePages(cfg) {
+    return cfg.pages.map((spec) => {
+        const p = typeof spec === 'string' ? { path: spec } : spec;
+        const any = p.path ?? p.local ?? p.remote;
+        if (!any)
+            throw new Error(`config: page needs "path", "local" or "remote": ${JSON.stringify(spec)}`);
+        const remotePath = p.remote ?? p.path;
+        return {
+            name: p.name ?? pageName(any),
+            path: p.path ?? null,
+            ref: p.ref ?? null,
+            remoteUrl: p.remote?.includes('://') ? p.remote : cfg.remote && remotePath ? join(cfg.remote, remotePath) : null,
+            localUrl: p.local?.includes('://') ? p.local : join(cfg.local.url, p.local ?? p.path ?? '/'),
+        };
+    });
+}
+const readNum = (file, fn) => {
+    try {
+        return fn(fs.readFileSync(file, 'utf8').trim());
+    }
+    catch {
+        return NaN;
+    }
+};
+// Container-aware limits: cgroup v2 quotas when present, host values otherwise.
+export function autoConcurrency() {
+    const cpuQuota = readNum('/sys/fs/cgroup/cpu.max', (s) => {
+        const [q, p] = s.split(' ');
+        return q === 'max' ? NaN : Number(q) / Number(p);
+    });
+    const cpus = Number.isFinite(cpuQuota) ? Math.max(1, Math.floor(cpuQuota)) : os.availableParallelism();
+    const memMax = readNum('/sys/fs/cgroup/memory.max', Number);
+    const mem = Number.isFinite(memMax) ? memMax : os.totalmem();
+    // ponytail: ~300MB browser base + ~400MB per full-page tab; measure if tabs OOM.
+    const byMem = Math.floor((mem / 2 ** 20 - 300) / 400);
+    return Math.max(1, Math.min(cpus, byMem));
+}
+// Cross-instance lock on the output dir (mkdir is atomic, also on NFS/shared
+// volumes). Other instances queue until it's released or goes stale.
+async function acquireLock(dir, { staleMs = 120_000, log }) {
+    const lock = path.join(dir, '.argus.lock');
+    for (let waited = false;;) {
+        try {
+            fs.mkdirSync(lock);
+            fs.writeFileSync(path.join(lock, 'owner'), `${os.hostname()} pid ${process.pid} ${new Date().toISOString()}`);
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+            let age = 0;
+            try {
+                age = Date.now() - fs.statSync(lock).mtimeMs;
+            }
+            catch {
+                continue;
+            } // released meanwhile
+            if (age > staleMs) {
+                fs.rmSync(lock, { recursive: true, force: true });
+                continue;
+            }
+            if (!waited) {
+                log(`queued: ${dir} is locked by another instance`);
+                waited = true;
+            }
+            await sleep(1000);
+        }
+    }
+    const beat = setInterval(() => { try {
+        const t = new Date();
+        fs.utimesSync(lock, t, t);
+    }
+    catch { } }, staleMs / 4);
+    beat.unref();
+    const release = () => { clearInterval(beat); fs.rmSync(lock, { recursive: true, force: true }); };
+    const onSignal = () => { release(); process.exit(130); };
+    process.once('SIGINT', onSignal).once('SIGTERM', onSignal);
+    return () => { process.off('SIGINT', onSignal).off('SIGTERM', onSignal); release(); };
+}
+async function isUp(url) {
+    try {
+        await fetch(url, { signal: AbortSignal.timeout(2000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Reuses a server already listening on local.url, otherwise runs
+// local.command and waits for the URL. Returns a stop function.
+export async function startServer({ url, command, cwd, timeout, logFile, log }) {
+    if (await isUp(url)) {
+        log(`using running server at ${url}`);
+        return () => { };
+    }
+    if (!command)
+        throw new Error(`${url} is not reachable and local.command is not set`);
+    log(`starting "${command}" (output: ${logFile})`);
+    const fd = fs.openSync(logFile, 'w');
+    const win = process.platform === 'win32';
+    const child = spawn(command, {
+        shell: true, cwd, detached: !win, stdio: ['ignore', fd, fd],
+        env: { ...process.env, BROWSER: 'none', FORCE_COLOR: '0' },
+    });
+    let exited = null;
+    child.on('exit', (code) => { exited = code ?? 'signal'; });
+    const stop = () => {
+        if (exited !== null || child.pid === undefined)
+            return;
+        try {
+            if (win)
+                execSync(`taskkill /pid ${child.pid} /T /F`, { stdio: 'ignore' });
+            else
+                process.kill(-child.pid, 'SIGTERM'); // whole group: npm → node → vite
+        }
+        catch { }
+    };
+    process.once('exit', stop);
+    const deadline = Date.now() + timeout;
+    while (!(await isUp(url))) {
+        if (exited !== null)
+            throw new Error(`"${command}" exited (${exited}) before ${url} came up, see ${logFile}`);
+        if (Date.now() > deadline) {
+            stop();
+            throw new Error(`timed out waiting for ${url}, see ${logFile}`);
+        }
+        await sleep(500);
+    }
+    log(`server up at ${url}`);
+    return stop;
+}
+async function pool(items, n, fn) {
+    let i = 0;
+    await Promise.all(Array.from({ length: Math.min(n, items.length) }, async () => {
+        while (i < items.length)
+            await fn(items[i++]);
+    }));
+}
+// Runs in the browser. Boxes of landmark elements, used to say *where* on
+// the page a diff is.
+function collectBoxes() {
+    const out = [];
+    for (const el of document.querySelectorAll('header,nav,main,section,article,aside,footer,form,[id],h1,h2,h3')) {
+        const r = el.getBoundingClientRect();
+        if (r.height < 8 || r.width < 8)
+            continue;
+        let label = el.tagName.toLowerCase();
+        if (el.id)
+            label += `#${el.id}`;
+        else if (typeof el.className === 'string' && el.className.trim())
+            label += `.${el.className.trim().split(/\s+/).slice(0, 2).join('.')}`;
+        if (/^H\d$/.test(el.tagName))
+            label += ` "${(el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 40)}"`;
+        out.push({ label, top: Math.round(r.top + scrollY), bottom: Math.round(r.bottom + scrollY) });
+        if (out.length >= 800)
+            break;
+    }
+    return out;
+}
+async function shoot(tab, url, outPath, cfg) {
+    const res = await tab.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
+    if (res && res.status() >= 400)
+        throw new Error(`${url} returned HTTP ${res.status()}`);
+    // Scroll through so IntersectionObserver-driven animations fire.
+    const vh = tab.viewportSize()?.height ?? 900;
+    const h = await tab.evaluate(() => document.documentElement.scrollHeight);
+    for (let y = 0; y < h; y += vh) {
+        await tab.evaluate((pos) => window.scrollTo(0, pos), y);
+        await tab.waitForTimeout(150);
+    }
+    await tab.evaluate(() => window.scrollTo(0, 0));
+    if (cfg.css)
+        await tab.addStyleTag({ content: cfg.css });
+    await tab.waitForTimeout(cfg.settle);
+    await tab.screenshot({ path: outPath, fullPage: true, animations: 'disabled' });
+    return tab.evaluate(collectBoxes);
+}
+function readHead(file, n) {
+    const b = Buffer.alloc(n);
+    const fd = fs.openSync(file, 'r');
+    try {
+        fs.readSync(fd, b, 0, n, 0);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return b;
+}
+function pngSize(file) {
+    const b = readHead(file, 24);
+    return { width: b.readUInt32BE(16), height: b.readUInt32BE(20) };
+}
+const isPng = (f) => readHead(f, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+// Merges changed rows into vertical bands and labels each with the
+// smallest page elements that cover it.
+export function toBands(lines, boxes, gap = 16, max = 30) {
+    const bands = [];
+    for (const y of lines) {
+        const last = bands.at(-1);
+        if (last && y - last.y2 <= gap) {
+            last.y2 = y;
+            last.rows++;
+        }
+        else
+            bands.push({ y1: y, y2: y, rows: 1 });
+    }
+    const top = bands.length > max ? [...bands].sort((a, b) => b.rows - a.rows).slice(0, max).sort((a, b) => a.y1 - b.y1) : bands;
+    return top.map((b) => {
+        const where = boxes
+            .filter((x) => x.top <= b.y2 && x.bottom >= b.y1)
+            .map((x) => ({ label: x.label, covers: x.top <= b.y1 && x.bottom >= b.y2, h: x.bottom - x.top }))
+            .sort((p, q) => (Number(q.covers) - Number(p.covers)) || (p.h - q.h))
+            .slice(0, 3)
+            .map((x) => x.label);
+        return { ...b, height: b.y2 - b.y1 + 1, where };
+    });
+}
+// Element boxes are CSS px; screenshots are device px.
+const scaleBoxes = (boxes, k) => (k === 1 ? boxes : boxes.map((b) => ({ ...b, top: b.top * k, bottom: b.bottom * k })));
+// Reference image for a page × viewport: page.ref ("x.png" for all viewports
+// or { mobile: "x.png" }), else the cfg.refs pattern if that file exists.
+export function refImage(page, vp, cfg) {
+    const explicit = typeof page.ref === 'string' ? page.ref : page.ref?.[vp];
+    if (explicit)
+        return path.resolve(cfg.root, explicit);
+    if (!cfg.refs)
+        return null;
+    const f = path.resolve(cfg.root, cfg.refs.replaceAll('{page}', page.name).replaceAll('{viewport}', vp));
+    return fs.existsSync(f) ? f : null;
+}
+async function runTask({ page, vp, size: vpSize, ctx, cfg }) {
+    const shotDir = path.join(cfg.out, vp);
+    const diffDir = path.join(cfg.diffDir, vp);
+    fs.mkdirSync(shotDir, { recursive: true });
+    fs.mkdirSync(diffDir, { recursive: true });
+    const image = refImage(page, vp, cfg);
+    const remote = image ?? path.join(shotDir, `${page.name}-remote.png`);
+    const local = path.join(shotDir, `${page.name}-local.png`);
+    const diff = path.join(diffDir, `${page.name}.png`);
+    const boxesFile = `${local}.boxes.json`;
+    const base = {
+        page: page.name, path: page.path, viewport: vp, refType: image ? 'image' : 'remote',
+        remoteUrl: image ? null : page.remoteUrl, localUrl: page.localUrl, remote, local, diff,
+    };
+    try {
+        if (image) {
+            if (!fs.existsSync(image))
+                throw new Error(`reference image not found: ${image}`);
+            if (!isPng(image))
+                throw new Error(`reference image must be PNG: ${image}`);
+        }
+        else if (!page.remoteUrl) {
+            throw new Error(`no reference: set "remote", or add a ref image for ${page.name} @ ${vp}`);
+        }
+        let boxes;
+        if (ctx) {
+            const tab = await ctx.newPage();
+            try {
+                if (!image)
+                    await shoot(tab, page.remoteUrl, remote, cfg);
+                boxes = await shoot(tab, page.localUrl, local, cfg);
+                fs.writeFileSync(boxesFile, JSON.stringify(boxes));
+            }
+            finally {
+                await tab.close();
+            }
+        }
+        else {
+            try {
+                boxes = JSON.parse(fs.readFileSync(boxesFile, 'utf8'));
+            }
+            catch {
+                boxes = [];
+            }
+        }
+        const r = await compare(remote, local, diff, { antialiasing: true, captureDiffLines: true, failOnLayoutDiff: false, noFailOnFsErrors: true });
+        if (!r.match && r.reason === 'file-not-exists')
+            throw new Error(`missing screenshot ${r.file} (run without --no-shoot)`);
+        const size = { remote: pngSize(remote), local: pngSize(local) };
+        if (image && size.remote.width !== size.local.width) {
+            throw new Error(`reference image is ${size.remote.width}px wide but the ${vp} screenshot is ${size.local.width}px; `
+                + 'match the viewport width (× deviceScaleFactor) to the design');
+        }
+        // odiff only compares the overlapping area, so a height change has to be flagged on its own.
+        const sizeMismatch = size.remote.width !== size.local.width || size.remote.height !== size.local.height;
+        if (r.match) {
+            fs.copyFileSync(local, diff); // odiff writes nothing on exact match
+            return { ...base, status: sizeMismatch ? 'diff' : 'match', diffPercentage: 0, diffCount: 0, size, sizeMismatch, bands: [] };
+        }
+        if (r.reason === 'layout-diff')
+            return { ...base, status: 'diff', diffPercentage: 100, diffCount: null, size, sizeMismatch: true, bands: [] };
+        if (r.reason !== 'pixel-diff')
+            throw new Error(`unexpected odiff result: ${JSON.stringify(r)}`);
+        const bands = toBands(r.diffLines ?? [], scaleBoxes(boxes, vpSize.deviceScaleFactor ?? 1));
+        return { ...base, status: 'diff', diffPercentage: r.diffPercentage, diffCount: r.diffCount, size, sizeMismatch, bands };
+    }
+    catch (e) {
+        return { ...base, status: 'error', error: errMsg(e).split('\n')[0] };
+    }
+}
+// Design images are rarely drawn at the real page height, so for them a height
+// difference is only a warning; they can also get a looser threshold.
+export function isFailed(r, cfg) {
+    if (r.status === 'error')
+        return true;
+    const image = r.refType === 'image';
+    if (r.sizeMismatch && !image)
+        return true;
+    return (r.diffPercentage ?? 0) > (image ? cfg.imageThreshold ?? cfg.threshold : cfg.threshold);
+}
+export async function run(cfg, opts = {}) {
+    const { log = () => { }, shoot: doShoot = true, server = true, only, viewports, concurrency, shard, browserWs } = opts;
+    fs.mkdirSync(cfg.out, { recursive: true });
+    let pages = resolvePages(cfg);
+    if (only?.length)
+        pages = pages.filter((p) => only.includes(p.name) || (p.path !== null && only.includes(p.path)));
+    let vps = Object.entries(cfg.viewports);
+    if (viewports?.length)
+        vps = vps.filter(([name]) => viewports.includes(name));
+    let tasks = pages.flatMap((page) => vps.map(([vp, size]) => ({ page, vp, size })));
+    if (shard) {
+        const [k, n] = shard.split('/').map(Number);
+        if (!(k >= 1 && k <= n))
+            throw new Error(`bad shard "${shard}", expected k/n`);
+        tasks = tasks.filter((_, i) => i % n === k - 1);
+    }
+    if (!tasks.length)
+        throw new Error('nothing to do: no pages/viewports match the filters');
+    const n = concurrency ?? cfg.concurrency ?? autoConcurrency();
+    log(`${pages.length} pages × ${vps.length} viewports, concurrency ${n}${shard ? `, shard ${shard}` : ''}`);
+    const release = await acquireLock(cfg.out, { log });
+    const results = [];
+    let stopServer = () => { };
+    try {
+        if (doShoot && server) {
+            stopServer = await startServer({
+                url: cfg.local.url, command: cfg.local.command, cwd: cfg.root,
+                timeout: cfg.serverTimeout, logFile: path.join(cfg.out, 'server.log'), log,
+            });
+        }
+        let browser;
+        if (doShoot)
+            browser = browserWs ? await chromium.connect(browserWs) : await launchBrowser(log);
+        try {
+            const ctxs = new Map();
+            if (browser) {
+                for (const [vp, s] of vps) {
+                    ctxs.set(vp, await browser.newContext({
+                        viewport: { width: s.width, height: s.height },
+                        deviceScaleFactor: s.deviceScaleFactor ?? 1,
+                        isMobile: !!s.isMobile,
+                        hasTouch: !!s.isMobile,
+                        ...(s.userAgent && { userAgent: s.userAgent }),
+                    }));
+                }
+            }
+            await pool(tasks, n, async (t) => {
+                log(`${t.page.name} @ ${t.vp}`);
+                results.push(await runTask({ ...t, ctx: ctxs.get(t.vp), cfg }));
+            });
+        }
+        finally {
+            if (browser)
+                await browser.close();
+        }
+    }
+    finally {
+        stopServer();
+        release();
+    }
+    const order = new Map(tasks.map((t, i) => [`${t.page.name}@${t.vp}`, i]));
+    const key = (r) => order.get(`${r.page}@${r.viewport}`) ?? 0;
+    results.sort((a, b) => key(a) - key(b));
+    for (const r of results)
+        r.failed = isFailed(r, cfg);
+    const failedResults = results.filter((r) => r.failed);
+    const summary = {
+        ok: failedResults.length === 0,
+        threshold: cfg.threshold,
+        shard: shard ?? null,
+        report: cfg.report,
+        counts: {
+            total: results.length,
+            passed: results.length - failedResults.length,
+            failed: failedResults.filter((r) => r.status !== 'error').length,
+            errors: results.filter((r) => r.status === 'error').length,
+        },
+        failed: failedResults.map((r) => `${r.page}@${r.viewport}`),
+        results,
+    };
+    writeReport(summary, cfg);
+    return summary;
+}

package/dist/init.d.ts

@@ -0,0 +1,25 @@
+import type { Log, RawConfig } from './types.ts';
+export interface Detected {
+    framework: string;
+    local: {
+        url: string;
+        command: string | null;
+    };
+    pages: string[];
+    remote: string | null;
+}
+export declare function detect(cwd?: string): Detected;
+export interface InitOptions {
+    cwd?: string;
+    remote?: string | null;
+    force?: boolean;
+    yes?: boolean;
+    log?: Log;
+}
+export interface InitResult {
+    configPath: string;
+    created: boolean;
+    config: RawConfig | null;
+    needsRemote?: boolean;
+}
+export declare function init({ cwd, remote, force, yes, log }?: InitOptions): Promise<InitResult>;

package/dist/init.js

@@ -0,0 +1,158 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { CONFIG_FILE, DEFAULTS } from './index.js';
+const PLACEHOLDER = 'https://example.com';
+const SELF = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).name;
+const SKIP_DIRS = /(^|\/)(node_modules|dist|build|out|\.git|\.next|\.astro|\.svelte-kit|\.nuxt|coverage|argus)(\/|$)/;
+function list(cwd, dir) {
+    try {
+        return fs.readdirSync(path.join(cwd, dir), { recursive: true })
+            .map((f) => String(f).split(path.sep).join('/'))
+            .filter((f) => !SKIP_DIRS.test(f));
+    }
+    catch {
+        return [];
+    }
+}
+const dynamic = (seg) => seg.startsWith('_') || seg.startsWith('@') || seg.includes('[');
+// File-based routing: pages/about.astro → /about, pages/blog/index.astro → /blog
+const fileRoutes = (dirs, ext) => (cwd) => dirs.flatMap((d) => list(cwd, d)
+    .filter((f) => ext.test(f))
+    .map((f) => f.replace(ext, '').split('/'))
+    .filter((segs) => segs[0] !== 'api' && !segs.some(dynamic))
+    .map((segs) => `/${(segs.at(-1) === 'index' ? segs.slice(0, -1) : segs).join('/')}`));
+// Folder-based routing: app/about/page.tsx → /about, (group) folders dropped
+const dirRoutes = (dirs, file) => (cwd) => dirs.flatMap((d) => list(cwd, d)
+    .filter((f) => file.test(f.split('/').at(-1) ?? ''))
+    .map((f) => f.split('/').slice(0, -1).filter((s) => !/^\(.*\)$/.test(s)))
+    .filter((segs) => segs[0] !== 'api' && !segs.some(dynamic))
+    .map((segs) => `/${segs.join('/')}`));
+const htmlRoutes = (cwd) => list(cwd, '.')
+    .filter((f) => /\.html$/.test(f) && !f.startsWith('public/'))
+    .map((f) => (f === 'index.html' ? '/' : `/${f.replace(/(^|\/)index\.html$/, '$1')}`));
+const FRAMEWORKS = [
+    { dep: 'next', name: 'Next.js', port: 3000, routes: (cwd) => [
+            ...dirRoutes(['app', 'src/app'], /^page\.(jsx?|tsx?|mdx?)$/)(cwd),
+            ...fileRoutes(['pages', 'src/pages'], /\.(jsx?|tsx?|mdx?)$/)(cwd),
+        ] },
+    { dep: 'astro', name: 'Astro', port: 4321, routes: fileRoutes(['src/pages'], /\.(astro|mdx?|html)$/) },
+    { dep: 'nuxt', name: 'Nuxt', port: 3000, routes: fileRoutes(['pages', 'app/pages'], /\.vue$/) },
+    { dep: '@sveltejs/kit', name: 'SvelteKit', port: 5173, routes: dirRoutes(['src/routes'], /^\+page\.(svelte|md|svx)$/) },
+    { dep: 'gatsby', name: 'Gatsby', port: 8000, routes: fileRoutes(['src/pages'], /\.(jsx?|tsx?)$/) },
+    { dep: '@remix-run/dev', name: 'Remix', port: 5173 },
+    { dep: '@react-router/dev', name: 'React Router', port: 5173 },
+    { dep: '@angular/core', name: 'Angular', port: 4200 },
+    { dep: 'react-scripts', name: 'Create React App', port: 3000 },
+    { dep: '@vue/cli-service', name: 'Vue CLI', port: 8080 },
+    { dep: '@11ty/eleventy', name: 'Eleventy', port: 8080 },
+    { dep: 'vite', name: 'Vite', port: 5173, routes: htmlRoutes },
+];
+function readJson(file) { try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+catch {
+    return null;
+} }
+function packageManager(cwd) {
+    const has = (f) => fs.existsSync(path.join(cwd, f));
+    if (has('pnpm-lock.yaml'))
+        return 'pnpm';
+    if (has('yarn.lock'))
+        return 'yarn';
+    if (has('bun.lockb') || has('bun.lock'))
+        return 'bun';
+    return 'npm';
+}
+function findRemote(cwd, pkg) {
+    if (pkg?.homepage && /^https?:\/\//.test(pkg.homepage))
+        return pkg.homepage;
+    for (const f of fs.readdirSync(cwd)) {
+        if (!/^(astro|next|nuxt|svelte|vite|gatsby-config|docusaurus)\.config\.|^gatsby-config\./.test(f))
+            continue;
+        const m = fs.readFileSync(path.join(cwd, f), 'utf8').match(/\b(?:site|siteUrl|url|baseUrl)\s*:\s*['"`](https?:\/\/[^'"`]+)/);
+        if (m)
+            return m[1];
+    }
+    try {
+        const cname = fs.readFileSync(path.join(cwd, 'CNAME'), 'utf8').trim() || fs.readFileSync(path.join(cwd, 'public/CNAME'), 'utf8').trim();
+        if (cname)
+            return `https://${cname}`;
+    }
+    catch { }
+    return null;
+}
+export function detect(cwd = process.cwd()) {
+    const pkg = readJson(path.join(cwd, 'package.json'));
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    const fw = FRAMEWORKS.find((f) => f.dep in deps);
+    const scripts = pkg?.scripts ?? {};
+    const script = ['dev', 'start', 'serve', 'preview'].find((s) => scripts[s]);
+    let command = script ? `${packageManager(cwd)} run ${script}` : null;
+    let port = fw?.port ?? 3000;
+    const portFlag = script && scripts[script].match(/(?:--port|-p)[ =](\d{2,5})/);
+    if (portFlag)
+        port = Number(portFlag[1]);
+    let pages = fw?.routes?.(cwd) ?? [];
+    if (!fw && fs.existsSync(path.join(cwd, 'index.html'))) {
+        pages = htmlRoutes(cwd);
+        command ??= `npx --yes serve -l ${port} .`;
+    }
+    pages = [...new Set(pages.length ? pages : ['/'])].sort((a, b) => (a === '/' ? -1 : b === '/' ? 1 : a.localeCompare(b))).slice(0, 50);
+    return {
+        framework: fw?.name ?? (command ? 'unknown' : 'static'),
+        local: { url: `http://localhost:${port}`, command },
+        pages,
+        remote: findRemote(cwd, pkg),
+    };
+}
+export async function init({ cwd = process.cwd(), remote, force = false, yes = false, log = console.error } = {}) {
+    const configPath = path.join(cwd, CONFIG_FILE);
+    if (fs.existsSync(configPath) && !force) {
+        log(`${CONFIG_FILE} already exists (use --force to regenerate)`);
+        return { configPath, created: false, config: readJson(configPath) };
+    }
+    const d = detect(cwd);
+    log(`detected: ${d.framework}${d.local.command ? `, start with "${d.local.command}"` : ''}, ${d.pages.length} page(s)`);
+    remote ??= d.remote;
+    if (!remote && !yes && process.stdin.isTTY) {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        remote = (await rl.question('Reference (remote) site URL to compare against: ')).trim() || null;
+        rl.close();
+    }
+    const config = {
+        remote: remote || PLACEHOLDER,
+        local: d.local,
+        pages: d.pages,
+        refs: 'designs/{page}-{viewport}.png',
+        viewports: DEFAULTS.viewports,
+        threshold: DEFAULTS.threshold,
+        out: DEFAULTS.out,
+        diffDir: `${DEFAULTS.out}/diffs`,
+        report: `${DEFAULTS.out}/report.html`,
+        css: DEFAULTS.css,
+    };
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    log(`wrote ${CONFIG_FILE}`);
+    const pkgPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+        const text = fs.readFileSync(pkgPath, 'utf8');
+        const pkg = JSON.parse(text);
+        if (!pkg.scripts?.['argus']) {
+            // The `argus` bin only exists when the package is installed in the project.
+            const installed = SELF in { ...pkg.dependencies, ...pkg.devDependencies };
+            pkg.scripts = { ...pkg.scripts, argus: installed ? 'argus' : `npx ${SELF}` };
+            const indent = text.match(/^[ \t]+(?=")/m)?.[0] ?? '  ';
+            fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`);
+            log(`added "argus" script to package.json: ${pkg.scripts.argus}`);
+        }
+    }
+    const gi = path.join(cwd, '.gitignore');
+    if (fs.existsSync(gi) && !/^\/?argus\/?$/m.test(fs.readFileSync(gi, 'utf8'))) {
+        fs.appendFileSync(gi, `\n/${DEFAULTS.out}/\n`);
+        log(`added /${DEFAULTS.out}/ to .gitignore`);
+    }
+    if (config.remote === PLACEHOLDER)
+        log(`set "remote" in ${CONFIG_FILE} to the site you compare against`);
+    return { configPath, created: true, config, needsRemote: config.remote === PLACEHOLDER };
+}

package/dist/report.d.ts

@@ -0,0 +1,3 @@
+import type { Config, Summary } from './types.ts';
+export declare const fmtPct: (n: number) => string;
+export declare function writeReport(summary: Summary, cfg: Config): string;

package/dist/report.js

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ENTITIES[c]);
+export const fmtPct = (n) => `${n.toFixed(n < 1 ? 3 : 2)}%`;
+const pct = (r) => (r.status === 'error' ? 'error' : fmtPct(r.diffPercentage ?? 0));
+const tone = (r) => (r.status === 'error' ? 'err' : r.failed ? 'bad' : r.status === 'match' ? 'ok' : 'warn');
+const id = (r) => `r-${r.page}-${r.viewport}`.replace(/[^\w-]/g, '_');
+function detail(r, rel) {
+    const head = `<summary><span class="dot ${tone(r)}"></span><b>${esc(r.page)}</b> <span class="muted">${esc(r.viewport)}</span>
+    <span class="pct ${tone(r)}">${pct(r)}</span></summary>`;
+    const refLabel = r.refType === 'image' ? 'reference' : 'remote';
+    const refLink = r.refType === 'image' ? `image <code>${esc(rel(r.remote))}</code>` : `remote <a href="${esc(r.remoteUrl)}">${esc(r.remoteUrl)}</a>`;
+    const links = `<p class="muted">${refLink} · local <a href="${esc(r.localUrl)}">${esc(r.localUrl)}</a></p>`;
+    if (r.status === 'error')
+        return `<details id="${id(r)}" class="card" open>${head}${links}<p class="errmsg">${esc(r.error)}</p></details>`;
+    const s = r.size;
+    const bandList = r.bands ?? [];
+    const facts = [
+        `${(r.diffCount ?? 0).toLocaleString('en')} px changed`,
+        `${refLabel} ${s.remote.width}×${s.remote.height}`,
+        `local ${s.local.width}×${s.local.height}`,
+    ];
+    const sizeNote = r.sizeMismatch
+        ? `<p class="warnmsg">Page size differs (height ${s.local.height - s.remote.height > 0 ? '+' : ''}${s.local.height - s.remote.height}px locally). Only the overlapping area is pixel-compared${r.refType === 'image' ? '. Design frames often have a different height than the real page, so this is a warning only' : ', so look for missing or extra content first'}.</p>`
+        : '';
+    // Bands are in remote-image coordinates (the diff image has the remote's size).
+    const H = s.remote.height || 1;
+    const overlay = bandList.map((b, i) => `<a class="band" href="#${id(r)}-b${i}" style="top:${(b.y1 / H) * 100}%;height:${Math.max((b.height / H) * 100, 0.3)}%" title="y ${b.y1}–${b.y2}"></a>`).join('');
+    const bands = bandList.length
+        ? `<table class="bands"><thead><tr><th>#</th><th>y (px)</th><th>height</th><th>where</th></tr></thead><tbody>${bandList.map((b, i) => `<tr id="${id(r)}-b${i}"><td>${i + 1}</td><td>${b.y1}–${b.y2}</td><td>${b.height}px</td><td>${b.where.map((w) => `<code>${esc(w)}</code>`).join(' ') || '<span class="muted">—</span>'}</td></tr>`).join('')}</tbody></table>`
+        : '';
+    const img = (f, cls) => `<img class="${cls}" loading="lazy" src="${esc(rel(f))}" alt="${cls}">`;
+    const viewer = `<div class="viewer" data-mode="diff">
+    <div class="modes">${['diff', 'remote', 'local', 'side'].map((m) => `<button data-m="${m}">${m === 'side' ? 'side by side' : m === 'remote' ? refLabel : m}</button>`).join('')}</div>
+    <div class="stage" style="max-width:${s.remote.width}px"><div class="frame">${img(r.diff, 'diff')}${overlay}</div>${img(r.remote, 'remote')}${img(r.local, 'local')}</div>
+    <div class="side">${img(r.remote, 'x')}${img(r.local, 'x')}${img(r.diff, 'x')}</div>
+  </div>`;
+    return `<details id="${id(r)}" class="card"${r.failed ? ' open' : ''}>${head}${links}<p class="facts">${facts.join(' · ')}</p>${sizeNote}${bands}${viewer}</details>`;
+}
+export function writeReport(summary, cfg) {
+    const dir = path.dirname(cfg.report);
+    fs.mkdirSync(dir, { recursive: true });
+    const rel = (f) => path.relative(dir, f).split(path.sep).join('/');
+    const { results, counts, threshold } = summary;
+    const pages = [...new Set(results.map((r) => r.page))];
+    const vps = [...new Set(results.map((r) => r.viewport))];
+    const by = new Map(results.map((r) => [`${r.page}@${r.viewport}`, r]));
+    const matrix = `<table class="matrix"><thead><tr><th>page</th>${vps.map((v) => `<th>${esc(v)}</th>`).join('')}</tr></thead><tbody>${pages.map((p) => `<tr><td>${esc(p)}</td>${vps.map((v) => {
+        const r = by.get(`${p}@${v}`);
+        return r ? `<td><a class="pct ${tone(r)}" href="#${id(r)}">${pct(r)}${r.sizeMismatch ? ' ↕' : ''}</a></td>` : '<td></td>';
+    }).join('')}</tr>`).join('')}</tbody></table>`;
+    const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Argus report</title>
+<style>
+:root{--bg:#fafafa;--fg:#1a1a1a;--muted:#6b6b6b;--card:#fff;--line:#e4e4e4;--ok:#1a7f37;--warn:#9a6700;--bad:#cf222e;--accent:#0969da}
+@media (prefers-color-scheme:dark){:root{--bg:#111;--fg:#e8e8e8;--muted:#9a9a9a;--card:#1b1b1b;--line:#2e2e2e;--ok:#3fb950;--warn:#d29922;--bad:#f85149;--accent:#58a6ff}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:14px/1.5 system-ui,sans-serif}
+main{max-width:1200px;margin:0 auto;padding:24px 16px}a{color:var(--accent)}h1{font-size:22px;margin:0 0 4px}
+.muted{color:var(--muted)}.chips{display:flex;gap:8px;flex-wrap:wrap;margin:16px 0}.chip{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:8px 14px}
+.chip b{font-size:20px;display:block}table{border-collapse:collapse;width:100%;background:var(--card)}th,td{border-bottom:1px solid var(--line);padding:6px 10px;text-align:left}
+.matrix{border:1px solid var(--line);border-radius:8px;overflow:hidden;margin-bottom:24px}.pct{font-variant-numeric:tabular-nums;font-weight:600;text-decoration:none}
+.ok{color:var(--ok)}.warn{color:var(--warn)}.bad,.err{color:var(--bad)}
+.card{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:10px 14px;margin:10px 0}
+summary{cursor:pointer;display:flex;gap:10px;align-items:center}summary .pct{margin-left:auto}
+.dot{width:10px;height:10px;border-radius:50%;background:currentColor;display:inline-block}
+.dot.ok{color:var(--ok)}.dot.warn{color:var(--warn)}.dot.bad,.dot.err{color:var(--bad)}
+.errmsg,.warnmsg{padding:8px 10px;border-radius:6px;border:1px solid}.errmsg{color:var(--bad)}.warnmsg{color:var(--warn)}
+.bands{margin:8px 0;font-size:13px}code{font-size:12px;background:var(--bg);padding:1px 5px;border-radius:4px;border:1px solid var(--line)}
+.modes{display:flex;gap:4px;margin:10px 0}.modes button{font:inherit;padding:4px 10px;border:1px solid var(--line);background:var(--bg);color:var(--fg);border-radius:6px;cursor:pointer}
+.viewer[data-mode=diff] [data-m=diff],.viewer[data-mode=remote] [data-m=remote],.viewer[data-mode=local] [data-m=local],.viewer[data-mode=side] [data-m=side]{background:var(--accent);color:#fff;border-color:var(--accent)}
+img{display:block;max-width:100%;height:auto;border:1px solid var(--line)}
+.stage img.remote,.stage img.local,.side{display:none}
+.viewer[data-mode=remote] .frame,.viewer[data-mode=local] .frame{display:none}
+.viewer[data-mode=remote] img.remote,.viewer[data-mode=local] img.local{display:block}
+.viewer[data-mode=side] .stage{display:none}.viewer[data-mode=side] .side{display:grid;grid-template-columns:repeat(3,1fr);gap:8px;align-items:start}
+.frame{position:relative}.band{position:absolute;left:0;right:0;background:color-mix(in srgb,var(--bad) 18%,transparent);border-left:4px solid var(--bad)}
+</style></head><body><main>
+<h1>Argus report</h1>
+<p class="muted">${esc(new Date().toISOString())} · ${cfg.remote ? `remote <a href="${esc(cfg.remote)}">${esc(cfg.remote)}</a>` : 'reference images'}${cfg.remote && cfg.refs ? ` + images <code>${esc(cfg.refs)}</code>` : ''} vs local <a href="${esc(cfg.local.url)}">${esc(cfg.local.url)}</a> · threshold ${threshold}%</p>
+<div class="chips"><div class="chip"><b class="${summary.ok ? 'ok' : 'bad'}">${summary.ok ? 'PASS' : 'FAIL'}</b>result</div>
+<div class="chip"><b>${counts.total}</b>checks</div><div class="chip"><b class="ok">${counts.passed}</b>passed</div>
+<div class="chip"><b class="bad">${counts.failed}</b>over threshold</div><div class="chip"><b class="bad">${counts.errors}</b>errors</div></div>
+${matrix}
+${results.map((r) => detail(r, rel)).join('\n')}
+</main><script>
+document.addEventListener('click',e=>{const b=e.target.closest('.modes button');if(b)b.closest('.viewer').dataset.mode=b.dataset.m});
+</script></body></html>`;
+    fs.writeFileSync(cfg.report, html);
+    return cfg.report;
+}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+export interface Viewport {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+    isMobile?: boolean;
+    userAgent?: string;
+}
+/** Reference image: one path for every viewport, or one per viewport. */
+export type RefSpec = string | Record<string, string>;
+export type PageSpec = string | {
+    path?: string;
+    name?: string;
+    remote?: string;
+    local?: string;
+    ref?: RefSpec;
+};
+/** argus.config.json as written by the user. */
+export interface RawConfig {
+    remote?: string;
+    local: {
+        url: string;
+        command?: string | null;
+    };
+    pages: PageSpec[];
+    refs?: string;
+    viewports?: Record<string, Viewport>;
+    threshold?: number;
+    imageThreshold?: number;
+    out?: string;
+    diffDir?: string;
+    report?: string;
+    css?: string;
+    settle?: number;
+    serverTimeout?: number;
+    concurrency?: number;
+}
+/** Config with defaults filled and paths made absolute. */
+export interface Config extends RawConfig {
+    root: string;
+    viewports: Record<string, Viewport>;
+    threshold: number;
+    out: string;
+    diffDir: string;
+    report: string;
+    css: string;
+    settle: number;
+    serverTimeout: number;
+}
+export interface Page {
+    name: string;
+    path: string | null;
+    ref: RefSpec | null;
+    remoteUrl: string | null;
+    localUrl: string;
+}
+export interface Box {
+    label: string;
+    top: number;
+    bottom: number;
+}
+export interface Band {
+    y1: number;
+    y2: number;
+    rows: number;
+    height: number;
+    /** Smallest page elements covering the band, e.g. `section#pricing`. */
+    where: string[];
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Result {
+    page: string;
+    path: string | null;
+    viewport: string;
+    refType: 'remote' | 'image';
+    remoteUrl: string | null;
+    localUrl: string;
+    /** Reference image path (remote screenshot or design image). */
+    remote: string;
+    local: string;
+    diff: string;
+    status: 'match' | 'diff' | 'error';
+    error?: string;
+    diffPercentage?: number;
+    diffCount?: number | null;
+    size?: {
+        remote: Size;
+        local: Size;
+    };
+    sizeMismatch?: boolean;
+    bands?: Band[];
+    failed?: boolean;
+}
+export interface Summary {
+    ok: boolean;
+    threshold: number;
+    shard: string | null;
+    report: string;
+    counts: {
+        total: number;
+        passed: number;
+        failed: number;
+        errors: number;
+    };
+    failed: string[];
+    results: Result[];
+}
+export type Log = (msg: string) => void;
+export interface RunOptions {
+    log?: Log;
+    shoot?: boolean;
+    server?: boolean;
+    only?: string[];
+    viewports?: string[];
+    concurrency?: number;
+    shard?: string;
+    browserWs?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@kaze-no-ryuu/argus",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Argus: visual diff of your local site against a live site or design images. Auto-detects framework and dev server, desktop/tablet/mobile, pinpoints changed elements, HTML report + JSON for CI and AI agents.",
+  "type": "module",
+  "bin": {
+    "argus": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./init": {
+      "types": "./dist/init.d.ts",
+      "default": "./dist/init.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "node --test \"test/*.test.ts\"",
+    "prepublishOnly": "npm run build && npm test",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=\"src/**\" \"test/*.test.ts\""
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ai-agent",
+    "astro",
+    "cli",
+    "diff",
+    "nextjs",
+    "odiff",
+    "pixel-diff",
+    "playwright",
+    "responsive",
+    "screenshot",
+    "screenshot-comparison",
+    "visual-regression",
+    "visual-testing",
+    "vite"
+  ],
+  "author": "Kaze",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Junkiez/argus.git"
+  },
+  "homepage": "https://github.com/Junkiez/argus#readme",
+  "bugs": {
+    "url": "https://github.com/Junkiez/argus/issues"
+  },
+  "dependencies": {
+    "odiff-bin": "^3.2.1",
+    "playwright": "^1.45.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "typescript": "^7.0.2"
+  }
+}