agentscreenshots 0.1.0

package/AGENT-INSTRUCTIONS.md

@@ -0,0 +1,102 @@
+# AgentScreenshots Agent Prompt
+
+Copy this into your coding agent's project instructions, custom instructions, skill, or rules file.
+
+```text
+You have access to the `agentshot` CLI for visual UI checks.
+
+Use it whenever you need to inspect a rendered webpage, verify frontend work, debug layout/CSS issues, check responsive behavior, or confirm that a visual change actually looks correct in the browser.
+
+Assume `agentshot` is already installed and configured. Do not install it, authenticate it, or change its configuration unless the user explicitly asks. If `agentshot` is not available, report that clearly and continue with the best available fallback.
+
+Default workflow:
+
+1. Identify the page URL to inspect.
+   - For local dev, use the active localhost URL, for example `http://127.0.0.1:5173`.
+   - For deployed work, use the preview/staging/production URL the user provided.
+
+2. Save screenshots into a predictable project folder:
+   - Prefer `.agents/screenshots/`.
+   - Use short descriptive filenames, for example `home.png`, `pricing-section.png`, `mobile-nav.png`.
+
+3. Capture the relevant view with `agentshot`.
+
+4. Inspect the saved PNG with your image-reading/viewing capability before judging the UI.
+
+5. If the UI is wrong, make a focused fix, capture again, and re-inspect.
+
+If `agentshot` itself fails, run:
+
+agentshot doctor
+
+Use the doctor output to identify whether the issue is missing auth, browser setup, API reachability, output permissions, or the target page itself.
+
+Use full-page capture when you need overall page context:
+
+agentshot "<url>" ".agents/screenshots/page.png" --scroll --wait 1000
+
+Use a fixed top slice when the issue is near the top of the page:
+
+agentshot "<url>" ".agents/screenshots/top.png" --height 1200 --wait 500
+
+Use a vertical slice when the issue is in a known scroll range:
+
+agentshot "<url>" ".agents/screenshots/slice.png" --from 1600 --to 2400 --wait 500
+
+Use selector capture for a specific section or component:
+
+agentshot "<url>" ".agents/screenshots/pricing.png" --selector "section:has-text('Pricing')" --padding 24 --wait 500
+
+Use `--nth` when multiple elements match:
+
+agentshot "<url>" ".agents/screenshots/card-2.png" --selector ".pricing-card" --nth 1 --padding 16 --wait 500
+
+Use mobile viewport checks for responsive layout:
+
+agentshot "<url>" ".agents/screenshots/mobile.png" --viewport 390x844 --scroll --wait 1000
+
+Use desktop viewport checks when layout width matters:
+
+agentshot "<url>" ".agents/screenshots/desktop.png" --viewport 1440x1000 --scroll --wait 1000
+
+Selector notes:
+
+- Plain CSS selectors work: `.hero`, `#pricing`, `[data-testid='nav']`.
+- Playwright text selectors work: `text=Pricing`.
+- Playwright text filters work: `section:has-text('Pricing')`.
+- XPath works when needed: `xpath=//section[.//h2[contains(., 'Pricing')]]`.
+
+When to use `--scroll`:
+
+- Use it for full-page screenshots.
+- Use it when images, animations, lazy-loaded sections, or scroll-triggered content may not render until the page is scrolled.
+- You usually do not need it for a small selector capture unless that section is lazy-loaded.
+
+When to use `--wait`:
+
+- Use `--wait 500` for normal UI pages.
+- Use `--wait 1000` or `--wait 2000` for pages with animations, remote images, or client-side data loading.
+- Use `--wait-for "<selector>"` if a specific element must exist before capture.
+
+Good commands:
+
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/home.png" --scroll --wait 1000
+agentshot "http://127.0.0.1:5173/pricing" ".agents/screenshots/pricing.png" --selector "main" --padding 16 --wait 500
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/mobile-home.png" --viewport 390x844 --scroll --wait 1000
+
+Do not:
+
+- Do not paste base64 screenshots into chat.
+- Do not rely only on command success; inspect the PNG.
+- Do not take huge full-page screenshots when a selector or slice would answer the question faster.
+- Do not keep re-capturing without making a concrete fix or forming a specific visual hypothesis.
+- Do not send feedback unless the user asks or the issue is clearly about the `agentshot` tool itself.
+```
+
+## Short Version
+
+Use this when the agent instruction surface is small:
+
+```text
+Use `agentshot` for visual UI checks. Capture rendered pages to `.agents/screenshots/`, then inspect the saved PNG before judging the UI. For full pages run `agentshot "<url>" ".agents/screenshots/page.png" --scroll --wait 1000`. For specific sections run `agentshot "<url>" ".agents/screenshots/section.png" --selector "section:has-text('Pricing')" --padding 24 --wait 500`. For mobile run `agentshot "<url>" ".agents/screenshots/mobile.png" --viewport 390x844 --scroll --wait 1000`. Prefer selector or vertical slice captures when possible. If the tool fails, run `agentshot doctor`. Do not paste base64 images into chat.
+```

package/LICENSE

@@ -0,0 +1,11 @@
+AgentScreenshots CLI License
+
+Copyright (c) 2026 Miha Cacic.
+All rights reserved.
+
+The AgentScreenshots CLI is proprietary software. You may install and use the
+package to access the AgentScreenshots service subject to the terms published
+at https://agentscreenshots.com/terms.
+
+You may not sell, sublicense, redistribute, host, or modify the package as a
+competing product without written permission.

package/README.md

@@ -0,0 +1,159 @@
+# AgentScreenshots CLI
+
+`agentshot` is a local-first screenshot CLI for AI coding agents. It runs Playwright on your machine, captures a rendered web page, writes a PNG/JPEG to disk, and reports one successful visual check to AgentScreenshots when a license key is configured.
+
+```bash
+npm install -g agentscreenshots
+agentshot auth ags_live_xxx
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/home.png" --scroll --wait 1000
+```
+
+## Install
+
+Requirements:
+
+- Node.js 20+
+- macOS, Linux, or Windows/WSL
+- A reachable URL to capture, including localhost URLs
+
+Install globally:
+
+```bash
+npm install -g agentscreenshots
+```
+
+The package installs the `agentshot` binary and downloads Playwright Chromium during `postinstall`. If browser installation is blocked in your environment, run this manually after install:
+
+```bash
+npx playwright install chromium
+```
+
+## Authenticate
+
+Create a free or paid license in the AgentScreenshots dashboard, then save it locally:
+
+```bash
+agentshot auth ags_live_xxx
+agentshot status
+```
+
+The config file is stored at:
+
+```text
+~/.config/agentshot/config.json
+```
+
+You can override config for CI or one-off runs:
+
+```text
+AGENTSHOT_API_URL
+AGENTSHOT_LICENSE_KEY
+AGENTSHOT_CONFIG
+```
+
+## Capture
+
+Basic full-page capture:
+
+```bash
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/home.png"
+```
+
+Lazy-loaded page:
+
+```bash
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/home.png" --scroll --wait 1000
+```
+
+Fixed top slice:
+
+```bash
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/hero.png" --height 1200
+```
+
+Vertical slice:
+
+```bash
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/slice.png" --from 1600 --to 2400
+```
+
+Specific section or component:
+
+```bash
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/pricing.png" \
+  --selector "section:has-text('Pricing')" --padding 24
+```
+
+Mobile viewport:
+
+```bash
+agentshot "http://127.0.0.1:5173" ".agents/screenshots/mobile.png" \
+  --viewport 390x844 --scroll --wait 1000
+```
+
+## Commands
+
+```bash
+agentshot URL OUTPUT [options]
+agentshot auth LICENSE_KEY [--api-url URL]
+agentshot status
+agentshot doctor
+agentshot feedback "MESSAGE" [--kind feedback|bug|idea]
+agentshot logout
+agentshot help
+```
+
+Important capture flags:
+
+- `--scroll`: scroll before capture to trigger lazy-loaded content.
+- `--wait MS`: wait after navigation/scroll before capture.
+- `--selector SELECTOR`: capture a Playwright/CSS selector.
+- `--section SELECTOR`: alias for `--selector`.
+- `--nth INDEX`: capture another selector match.
+- `--padding PX`: add padding around selector captures.
+- `--height PX`: capture from `--from` or page top to a fixed height.
+- `--from PX --to PX`: capture a vertical page slice.
+- `--viewport WIDTHxHEIGHT`: set viewport size.
+- `--wait-for CSS`: wait for an element before capture.
+- `--wait-until STATE`: `load`, `domcontentloaded`, or `networkidle`.
+- `--json`: print machine-readable output.
+- `--no-report`: skip usage reporting.
+
+Selectors are Playwright locators, so plain CSS, `text=Pricing`, `section:has-text('Pricing')`, and `xpath=...` work.
+
+## Agent Workflow
+
+Tell your coding agent:
+
+1. Save captures to `.agents/screenshots/`.
+2. Use `agentshot` after meaningful UI changes.
+3. Prefer selector or slice captures over huge full-page captures when possible.
+4. Open and inspect the saved PNG before judging the UI.
+
+The package includes [`AGENT-INSTRUCTIONS.md`](./AGENT-INSTRUCTIONS.md), a copy-paste prompt for Claude Code, Codex, Cursor, Windsurf, and OpenCode.
+
+## Usage Reporting
+
+Successful screenshots report one visual check when a license key is configured. Failed captures do not count. If the backend is temporarily unreachable, the event is queued at:
+
+```text
+~/.config/agentshot/usage-queue.jsonl
+```
+
+Queued events sync on the next successful online capture.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm run build
+npm link
+agentshot --version
+```
+
+Package smoke test:
+
+```bash
+npm pack --dry-run
+```

package/dist/capture.js

@@ -0,0 +1,191 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname, extname, resolve } from 'node:path';
+import { chromium } from 'playwright';
+import { getFileSize, getTargetKind, reportCheck } from './reporting.js';
+const PACKAGE_VERSION = '0.1.0';
+function sleep(ms) {
+    return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+function clampClip(clip, pageWidth, pageHeight) {
+    const x = Math.max(0, Math.floor(clip.x));
+    const y = Math.max(0, Math.floor(clip.y));
+    const width = Math.max(1, Math.min(Math.floor(clip.width), Math.floor(pageWidth - x)));
+    const height = Math.max(1, Math.min(Math.floor(clip.height), Math.floor(pageHeight - y)));
+    return { x, y, width, height };
+}
+function getFormat(output) {
+    const extension = extname(output).toLowerCase();
+    return extension === '.jpg' || extension === '.jpeg' ? 'jpeg' : 'png';
+}
+async function getPageSize(page) {
+    return page.evaluate(() => {
+        const root = document.scrollingElement || document.documentElement;
+        const body = document.body;
+        return {
+            width: Math.max(root.scrollWidth, body?.scrollWidth ?? 0, window.innerWidth),
+            height: Math.max(root.scrollHeight, body?.scrollHeight ?? 0, window.innerHeight)
+        };
+    });
+}
+async function triggerLazyLoadedContent(page) {
+    await page.evaluate(async () => {
+        const sleepInPage = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+        document
+            .querySelectorAll('img[loading="lazy"]')
+            .forEach((image) => (image.loading = 'eager'));
+        const root = document.scrollingElement || document.documentElement;
+        const viewport = window.innerHeight || 800;
+        const step = Math.max(240, Math.floor(viewport * 0.75));
+        const height = () => Math.max(root.scrollHeight, document.body?.scrollHeight ?? 0);
+        for (let y = 0; y < height(); y += step) {
+            window.scrollTo(0, y);
+            window.dispatchEvent(new Event('scroll'));
+            await sleepInPage(180);
+        }
+        window.scrollTo(0, height());
+        window.dispatchEvent(new Event('scroll'));
+        await sleepInPage(350);
+        window.scrollTo(0, 0);
+        await sleepInPage(250);
+    });
+}
+async function computeSelectorClip(page, selector, index, padding, timeoutMs) {
+    const locator = page.locator(selector).nth(index);
+    await locator.waitFor({ state: 'visible', timeout: timeoutMs });
+    await locator.scrollIntoViewIfNeeded();
+    await sleep(100);
+    const box = await locator.evaluate((element, pad) => {
+        const rect = element.getBoundingClientRect();
+        return {
+            x: rect.left + window.scrollX - pad,
+            y: rect.top + window.scrollY - pad,
+            width: rect.width + pad * 2,
+            height: rect.height + pad * 2
+        };
+    }, padding);
+    return box;
+}
+function computeVerticalClip(options, pageWidth, pageHeight) {
+    const y = options.fromY ?? 0;
+    let height = null;
+    if (options.toY !== null) {
+        height = options.toY - y;
+    }
+    else if (options.clipHeight !== null) {
+        height = options.clipHeight;
+    }
+    if (height === null) {
+        return null;
+    }
+    if (height <= 0) {
+        throw new Error('Clip height must be greater than 0.');
+    }
+    return clampClip({ x: 0, y, width: pageWidth, height }, pageWidth, pageHeight);
+}
+async function launchBrowser(options) {
+    const executablePath = options.browser === 'chrome' ? undefined : undefined;
+    return chromium.launch({
+        channel: options.browser === 'chrome' ? 'chrome' : undefined,
+        executablePath,
+        headless: !options.headed
+    });
+}
+export async function capture(options) {
+    const startedAt = Date.now();
+    const output = resolve(options.output);
+    await mkdir(dirname(output), { recursive: true });
+    const browser = await launchBrowser(options);
+    try {
+        const page = await browser.newPage({
+            viewport: {
+                width: options.width,
+                height: options.viewportHeight
+            },
+            deviceScaleFactor: options.deviceScaleFactor
+        });
+        page.setDefaultTimeout(options.timeoutMs);
+        await page.goto(options.url, {
+            waitUntil: options.waitForLoadState,
+            timeout: options.timeoutMs
+        });
+        if (options.waitForSelector) {
+            await page.locator(options.waitForSelector).first().waitFor({
+                state: 'visible',
+                timeout: options.timeoutMs
+            });
+        }
+        if (options.scroll) {
+            await triggerLazyLoadedContent(page);
+        }
+        if (options.waitMs > 0) {
+            await sleep(options.waitMs);
+        }
+        const pageSize = await getPageSize(page);
+        const format = getFormat(output);
+        let screenshotWidth = pageSize.width;
+        let screenshotHeight = pageSize.height;
+        let mode = 'full-page';
+        if (options.selector) {
+            const selectorClip = await computeSelectorClip(page, options.selector, options.selectorIndex, options.padding, options.timeoutMs);
+            const clip = clampClip(selectorClip, pageSize.width, pageSize.height);
+            await page.screenshot({ path: output, fullPage: true, clip, type: format });
+            screenshotWidth = clip.width;
+            screenshotHeight = clip.height;
+            mode = 'selector';
+        }
+        else {
+            const verticalClip = computeVerticalClip(options, pageSize.width, pageSize.height);
+            if (verticalClip) {
+                await page.screenshot({ path: output, fullPage: true, clip: verticalClip, type: format });
+                screenshotWidth = verticalClip.width;
+                screenshotHeight = verticalClip.height;
+                mode = 'clip';
+            }
+            else {
+                await page.screenshot({ path: output, fullPage: options.fullPage, type: format });
+                screenshotWidth = options.fullPage ? pageSize.width : options.width;
+                screenshotHeight = options.fullPage ? pageSize.height : options.viewportHeight;
+            }
+        }
+        const durationMs = Date.now() - startedAt;
+        const fileSizeBytes = await getFileSize(output);
+        let reported = false;
+        let reportStatus = 'skipped';
+        let reportReason;
+        if (options.report) {
+            const report = await reportCheck({
+                apiUrl: options.apiUrl,
+                licenseKey: options.licenseKey,
+                metadata: {
+                    cliVersion: PACKAGE_VERSION,
+                    targetKind: getTargetKind(options.url),
+                    viewportWidth: options.width,
+                    viewportHeight: options.viewportHeight,
+                    waitMs: options.waitMs,
+                    scroll: options.scroll,
+                    durationMs,
+                    fileSizeBytes,
+                    format
+                }
+            });
+            reported = report.reported;
+            reportStatus = report.status;
+            reportReason = report.reason;
+        }
+        return {
+            output,
+            url: options.url,
+            width: screenshotWidth,
+            height: screenshotHeight,
+            fileSizeBytes,
+            durationMs,
+            mode,
+            reported,
+            reportStatus,
+            reportReason
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/config.js

@@ -0,0 +1,52 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+const DEFAULT_API_URL = 'https://agentscreenshots.com';
+export function getConfigPath() {
+    if (process.env.AGENTSHOT_CONFIG) {
+        return process.env.AGENTSHOT_CONFIG;
+    }
+    const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(configHome, 'agentshot', 'config.json');
+}
+export async function readConfig() {
+    const path = getConfigPath();
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return {};
+        }
+        throw error;
+    }
+}
+export async function writeConfig(config) {
+    const path = getConfigPath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    return path;
+}
+export async function clearLicenseKey() {
+    const config = await readConfig();
+    const nextConfig = { ...config };
+    const hadLicenseKey = Boolean(nextConfig.licenseKey);
+    delete nextConfig.licenseKey;
+    const path = await writeConfig(nextConfig);
+    return {
+        path,
+        hadLicenseKey,
+        envOverrideActive: Boolean(process.env.AGENTSHOT_LICENSE_KEY)
+    };
+}
+export async function resolveApiUrl(explicitApiUrl) {
+    const config = await readConfig();
+    return stripTrailingSlash(explicitApiUrl || process.env.AGENTSHOT_API_URL || config.apiUrl || DEFAULT_API_URL);
+}
+export async function resolveLicenseKey(explicitLicenseKey) {
+    const config = await readConfig();
+    return explicitLicenseKey || process.env.AGENTSHOT_LICENSE_KEY || config.licenseKey || null;
+}
+export function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}

package/dist/doctor.js

@@ -0,0 +1,148 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { chromium } from 'playwright';
+import { getConfigPath, readConfig, resolveApiUrl, resolveLicenseKey } from './config.js';
+import { validateLicense } from './reporting.js';
+function getOverallStatus(checks) {
+    if (checks.some((check) => check.status === 'fail')) {
+        return 'fail';
+    }
+    if (checks.some((check) => check.status === 'warn')) {
+        return 'warn';
+    }
+    return 'ok';
+}
+function getNodeMajor() {
+    return Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+}
+async function checkWritableTempFile() {
+    const directory = await mkdtemp(join(tmpdir(), 'agentshot-'));
+    const path = join(directory, 'doctor.txt');
+    try {
+        await writeFile(path, 'ok\n');
+        return {
+            name: 'output',
+            status: 'ok',
+            message: `Can write screenshot output files (${directory}).`
+        };
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+async function checkBrowser() {
+    const browser = await chromium.launch();
+    try {
+        const page = await browser.newPage();
+        await page.setContent('<!doctype html><title>agentshot doctor</title><p>ok</p>');
+        return {
+            name: 'browser',
+            status: 'ok',
+            message: 'Playwright Chromium launches successfully.'
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}
+export async function runDoctor(options) {
+    const checks = [];
+    checks.push({
+        name: 'node',
+        status: getNodeMajor() >= 20 ? 'ok' : 'fail',
+        message: `Node ${process.versions.node} detected. agentshot requires Node 20+.`
+    });
+    try {
+        await readConfig();
+        checks.push({
+            name: 'config',
+            status: 'ok',
+            message: `Config path is readable: ${getConfigPath()}`
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: 'config',
+            status: 'fail',
+            message: error instanceof Error ? error.message : 'Config could not be read.'
+        });
+    }
+    let apiUrl = '';
+    try {
+        apiUrl = await resolveApiUrl(options.apiUrl);
+        checks.push({
+            name: 'api-url',
+            status: 'ok',
+            message: `API URL: ${apiUrl}`
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: 'api-url',
+            status: 'fail',
+            message: error instanceof Error ? error.message : 'API URL could not be resolved.'
+        });
+    }
+    const licenseKey = await resolveLicenseKey(options.licenseKey);
+    checks.push({
+        name: 'license-key',
+        status: licenseKey ? 'ok' : 'warn',
+        message: licenseKey
+            ? 'License key is configured.'
+            : 'No license key configured. Run `agentshot auth ags_live_...` when ready.'
+    });
+    try {
+        checks.push(await checkBrowser());
+    }
+    catch (error) {
+        checks.push({
+            name: 'browser',
+            status: 'fail',
+            message: error instanceof Error
+                ? error.message
+                : 'Playwright Chromium could not launch.'
+        });
+    }
+    try {
+        checks.push(await checkWritableTempFile());
+    }
+    catch (error) {
+        checks.push({
+            name: 'output',
+            status: 'fail',
+            message: error instanceof Error ? error.message : 'Could not write a temp output file.'
+        });
+    }
+    if (licenseKey && apiUrl) {
+        try {
+            const result = await validateLicense(options);
+            const license = result.body?.license;
+            checks.push({
+                name: 'api-license',
+                status: result.ok ? 'ok' : 'fail',
+                message: result.ok
+                    ? `License ${license?.keyPrefix ?? ''} validates: ${license?.usedChecks ?? 0}/${license?.quotaChecks ?? 0} checks used.`
+                    : `License validation failed with HTTP ${result.status}.`
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: 'api-license',
+                status: 'fail',
+                message: error instanceof Error ? error.message : 'License validation failed.'
+            });
+        }
+    }
+    else {
+        checks.push({
+            name: 'api-license',
+            status: 'skip',
+            message: 'Skipped because no license key is configured.'
+        });
+    }
+    return {
+        status: getOverallStatus(checks),
+        checks
+    };
+}