{"_id":"@americano98/peye","_rev":"4-e881fbbced3f75a3464437a31d740e9f","name":"@americano98/peye","dist-tags":{"latest":"0.2.5"},"versions":{"0.1.0":{"name":"@americano98/peye","version":"0.1.0","keywords":["cli","visual-diff","figma","playwright","pixelmatch"],"license":"MIT","_id":"@americano98/peye@0.1.0","maintainers":[{"name":"americano98","email":"americano_98_000@mail.ru"}],"homepage":"https://github.com/americano98/peye#readme","bugs":{"url":"https://github.com/americano98/peye/issues"},"bin":{"peye":"dist/bin.js"},"dist":{"shasum":"d5dbf2bd6ad9f00c029d291d467b320fbd03ec6d","tarball":"https://registry.npmjs.org/@americano98/peye/-/peye-0.1.0.tgz","fileCount":5,"integrity":"sha512-k+CIrwUXkWKuZ9rCHzlTWe7HXaPyzDbj73nxmDT2QuE9eHJsyuKqw8kUFXZyhosOwGFKi2Dm//hJ3vZemSM5cA==","signatures":[{"sig":"MEYCIQCe3cfQbFoxg77lHsi5jyZFhuiviWk6OkrWLVRu83658AIhANz7NRktXFlHUJIdcdzaCy6zNWWleDwp6iap9giaNBMZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":335506},"type":"module","engines":{"node":">=22"},"gitHead":"987324012d4e796689b63d4a3f80ac709812d1b2","scripts":{"dev":"tsx src/cli/bin.ts","lint":"eslint .","test":"vitest run","build":"tsup","check":"pnpm format:check && pnpm typecheck && pnpm lint && pnpm test && pnpm build","clean":"rm -rf coverage dist test-output peye-output","format":"prettier . --write","prepack":"pnpm check","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier . --check"},"_npmUser":{"name":"americano98","email":"americano_98_000@mail.ru"},"repository":{"url":"git+https://github.com/americano98/peye.git","type":"git"},"_npmVersion":"10.9.3","description":"Standalone CLI for visual diffing UI screenshots against Figma references.","directories":{},"_nodeVersion":"22.18.0","dependencies":{"sharp":"0.34.5","commander":"^14.0.3","pixelmatch":"7.1.0","playwright":"1.58.2","@modelcontextprotocol/sdk":"1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.11.0","devDependencies":{"tsx":"4.21.0","tsup":"8.5.1","eslint":"10.0.3","vitest":"^4.1.0","globals":"17.4.0","prettier":"3.8.1","@eslint/js":"10.0.1","typescript":"5.9.3","@types/node":"^22.19.15","typescript-eslint":"8.57.1","eslint-config-prettier":"10.1.8"},"_npmOperationalInternal":{"tmp":"tmp/peye_0.1.0_1773788757900_0.14312999765833512","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@americano98/peye","version":"0.1.1","keywords":["cli","visual-diff","figma","playwright","pixelmatch"],"license":"MIT","_id":"@americano98/peye@0.1.1","maintainers":[{"name":"americano98","email":"americano_98_000@mail.ru"}],"homepage":"https://github.com/americano98/peye#readme","bugs":{"url":"https://github.com/americano98/peye/issues"},"bin":{"peye":"dist/bin.js"},"dist":{"shasum":"6e8a93300840d6f443ac79da9cd05ec9cf4b9b0b","tarball":"https://registry.npmjs.org/@americano98/peye/-/peye-0.1.1.tgz","fileCount":5,"integrity":"sha512-Uf9ldlEG0/FwmVrEW33b1jcMPa7p6Wg5vNzmCBGhtPQk3Nw3eNy4euHidpUy5CqEpvb3iYkVSMVyAeZhLwWidg==","signatures":[{"sig":"MEUCICRfAgcFlL8zmiCrNuNpe8sJ6gicriH6ZG8JcZVGbXO5AiEA2Yd/xh+VQAO72gK+xyl1N7bw1c162qbiRrYLh5EFK9A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":378415},"type":"module","engines":{"node":">=22"},"gitHead":"b8c673488dc000d01c9f97381fa851848807be63","scripts":{"dev":"tsx src/cli/bin.ts","lint":"eslint .","test":"vitest run","build":"tsup","check":"pnpm format:check && pnpm typecheck && pnpm lint && pnpm test && pnpm build","clean":"rm -rf coverage dist test-output peye-output","format":"prettier . --write","prepack":"pnpm check","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier . --check"},"_npmUser":{"name":"americano98","email":"americano_98_000@mail.ru"},"repository":{"url":"git+https://github.com/americano98/peye.git","type":"git"},"_npmVersion":"10.9.3","description":"Standalone CLI for visual diffing UI screenshots against Figma references.","directories":{},"_nodeVersion":"22.18.0","dependencies":{"sharp":"0.34.5","commander":"^14.0.3","pixelmatch":"7.1.0","playwright":"1.58.2","@modelcontextprotocol/sdk":"1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.11.0","devDependencies":{"tsx":"4.21.0","tsup":"8.5.1","eslint":"10.0.3","vitest":"^4.1.0","globals":"17.4.0","prettier":"3.8.1","@eslint/js":"10.0.1","typescript":"5.9.3","@types/node":"^22.19.15","typescript-eslint":"8.57.1","eslint-config-prettier":"10.1.8"},"_npmOperationalInternal":{"tmp":"tmp/peye_0.1.1_1773834568686_0.6513352525466292","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@americano98/peye","version":"0.2.0","keywords":["cli","figma","pixelmatch","playwright","visual-diff"],"license":"MIT","_id":"@americano98/peye@0.2.0","maintainers":[{"name":"americano98","email":"americano_98_000@mail.ru"}],"homepage":"https://github.com/americano98/peye#readme","bugs":{"url":"https://github.com/americano98/peye/issues"},"bin":{"peye":"dist/bin.js"},"dist":{"shasum":"c0d8aa6f96d16fcdb4e12b66c18d16da5378ef3e","tarball":"https://registry.npmjs.org/@americano98/peye/-/peye-0.2.0.tgz","fileCount":5,"integrity":"sha512-1z6kAZM0kJE0AsRTAbsguSGDM8IHTXWzJcbIZ1/aDqaR2OQu2/B+Yxx9drd1yU6zKoV4HEhFMKFzBWvbYfFLSQ==","signatures":[{"sig":"MEUCIQCj6O8Yg5FEM5Sg4lj7GEnJYmg6gPvd6EUX1vGxNK35xgIgMgKCJbPlOeEIG/Ls3DzUYp3hXZ+m7NVuzPvnCHr8VoA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":569961},"type":"module","engines":{"node":">=22"},"gitHead":"51b0e20ad2bdb6246b1edd6d1c52dcba7b853c2f","scripts":{"dev":"tsx src/cli/bin.ts","lint":"oxlint --type-aware .","test":"vitest run","build":"tsup","check":"pnpm format:check && pnpm typecheck && pnpm lint && pnpm test && pnpm build","clean":"rm -rf coverage dist test-output peye-output","format":"oxfmt .","prepack":"pnpm check","lint:fix":"oxlint --type-aware --fix .","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"oxfmt --check ."},"_npmUser":{"name":"americano98","email":"americano_98_000@mail.ru"},"repository":{"url":"git+https://github.com/americano98/peye.git","type":"git"},"_npmVersion":"10.9.3","description":"Standalone CLI for visual diffing UI screenshots against Figma references.","directories":{},"_nodeVersion":"22.18.0","dependencies":{"sharp":"0.34.5","commander":"^14.0.3","pixelmatch":"7.1.0","playwright":"1.58.2","@modelcontextprotocol/sdk":"1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.11.0","devDependencies":{"tsx":"4.21.0","tsup":"8.5.1","oxfmt":"0.41.0","oxlint":"1.56.0","vitest":"^4.1.0","typescript":"5.9.3","@types/node":"^22.19.15","oxlint-tsgolint":"0.17.0"},"_npmOperationalInternal":{"tmp":"tmp/peye_0.2.0_1773872998702_0.3069519720123861","host":"s3://npm-registry-packages-npm-production"}},"0.2.5":{"name":"@americano98/peye","version":"0.2.5","description":"Standalone CLI for visual diffing UI screenshots against Figma references.","keywords":["cli","figma","pixelmatch","playwright","visual-diff"],"homepage":"https://github.com/americano98/peye#readme","bugs":{"url":"https://github.com/americano98/peye/issues"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/americano98/peye.git"},"bin":{"peye":"dist/bin.js"},"type":"module","publishConfig":{"access":"public"},"scripts":{"build":"tsup","clean":"rm -rf coverage dist test-output peye-output","dev":"tsx src/cli/bin.ts","format":"oxfmt .","format:check":"oxfmt --check .","lint":"oxlint --type-aware .","lint:fix":"oxlint --type-aware --fix .","prepack":"pnpm check","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","check":"pnpm format:check && pnpm typecheck && pnpm lint && pnpm test && pnpm build"},"dependencies":{"@modelcontextprotocol/sdk":"1.27.1","commander":"^14.0.3","pixelmatch":"7.1.0","playwright":"1.58.2","sharp":"0.34.5"},"devDependencies":{"@types/node":"^22.19.15","oxfmt":"0.41.0","oxlint":"1.56.0","oxlint-tsgolint":"0.17.0","tsup":"8.5.1","tsx":"4.21.0","typescript":"5.9.3","vitest":"^4.1.0"},"engines":{"node":">=22"},"packageManager":"pnpm@10.11.0","_id":"@americano98/peye@0.2.5","gitHead":"fde5e04285834fd63eae20bd6d4ae60a84a9d810","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-Dynh5dkDxY/sBHVIYh/ZJ720X35KZYZ/gbYaH99IzgUE5TtDCgDtqDnBpWhklO49v1D/gGloHDAjiwEdwK8kOA==","shasum":"4bd523a272540a4b84185c73f5fd903aa216d27f","tarball":"https://registry.npmjs.org/@americano98/peye/-/peye-0.2.5.tgz","fileCount":5,"unpackedSize":946432,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQClbV/H7JKlJDd47FNA9q1jF5Ec8l0oaPooh60+GwtTNwIhAK0xXBwPn5s/Rt1N1BG5utOFVjscbsrcLTEqEnlQK97b"}]},"_npmUser":{"name":"americano98","email":"americano_98_000@mail.ru"},"directories":{},"maintainers":[{"name":"americano98","email":"americano_98_000@mail.ru"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/peye_0.2.5_1774205238447_0.5704930110629558"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-17T23:05:57.679Z","modified":"2026-03-22T18:47:18.729Z","0.1.0":"2026-03-17T23:05:58.092Z","0.1.1":"2026-03-18T11:49:28.839Z","0.2.0":"2026-03-18T22:29:58.859Z","0.2.5":"2026-03-22T18:47:18.621Z"},"bugs":{"url":"https://github.com/americano98/peye/issues"},"license":"MIT","homepage":"https://github.com/americano98/peye#readme","keywords":["cli","figma","pixelmatch","playwright","visual-diff"],"repository":{"type":"git","url":"git+https://github.com/americano98/peye.git"},"description":"Standalone CLI for visual diffing UI screenshots against Figma references.","maintainers":[{"name":"americano98","email":"americano_98_000@mail.ru"}],"readme":"# peye\n\n`peye` is a standalone CLI for visual diffing an implemented UI against a Figma reference or another screenshot. It is built for deterministic local execution and agent-driven validation workflows.\n\nThe comparison core is intentionally separated from screenshot acquisition, so the tool stays scriptable, predictable, and easy to embed into automation pipelines.\n\n## Highlights\n\n- Compare a live preview URL or a local screenshot against a Figma node or another image\n- Capture a specific section with `--selector` or directly from a preview URL hash\n- Ignore known preview noise such as sticky banners or third-party overlays\n- Generate deterministic artifacts: `report.json`, `overlay.png`, `diff.png`, `heatmap.png`, and normalized inputs\n- Return an actionable recommendation: `pass`, `pass_with_tolerated_differences`, `retry_fix`, or `needs_human_review`\n\n## Typical Use Cases\n\n- Validate a locally implemented section against a Figma frame\n- Compare two screenshots in CI or local review workflows\n- Run an agent loop: compare, inspect `report.json`, fix, and rerun\n- Triage whether a mismatch is small, fixable, or should be escalated to human review\n\n## Requirements\n\n- Node.js `>= 22`\n- Playwright Chromium for live URL capture\n- One of these when `--reference` is a Figma URL:\n  - Figma desktop MCP\n  - remote Figma MCP authorization in an interactive terminal\n  - `FIGMA_TOKEN` for REST fallback or CI\n\nIf you only compare local images, you do not need a browser download.\n\n## Installation\n\nInstall the published CLI:\n\n```bash\nnpm install -g @americano98/peye\npeye install chromium\npeye --help\n```\n\nBuild from source:\n\n```bash\npnpm install\npnpm build\nnode dist/bin.js --help\n```\n\n`peye install chromium` is only required for live URL capture. Pure image-to-image comparison works without a browser download.\n\n## Quick Start\n\nCompare a live section against a Figma node:\n\n```bash\npeye compare \\\n  --preview http://localhost:3000/#hero \\\n  --reference \"https://www.figma.com/design/FILE_KEY/Mockup?node-id=1-2\" \\\n  --viewport 1920 \\\n  --output ./tmp/peye/hero\n```\n\n`peye` writes the comparison artifacts into the output directory and uses `report.json` as the main machine-readable contract.\n\nCompare two local images:\n\n```bash\npeye compare \\\n  --preview ./artifacts/preview.png \\\n  --reference ./artifacts/reference.png \\\n  --output ./tmp/peye/run\n```\n\n## Output\n\nEach run writes a deterministic output bundle:\n\n- `report.json`: primary machine-readable result\n- `preview.png`: normalized preview image used for analysis\n- `reference.png`: normalized reference image used for analysis\n- `overlay.png`: blended reference plus preview image\n- `diff.png`: raw pixel diff image\n- `heatmap.png`: highlighted mismatch regions\n- `summary.md`: compact human-readable explanation of the main findings\n\nFor automation, the most important fields are:\n\n- `summary.recommendation`\n- `summary.decisionTrace`\n- `summary.topActions`\n- `summary.agentChecks`\n- `summary.primaryBlockers`\n- `summary.safeToAutofix`\n- `summary.requiresRecapture`\n- `summary.requiresSanityCheck`\n- `findings`\n- `error`\n\n## Documentation\n\n- [Documentation index](./docs/README.md)\n- [CLI usage and examples](./docs/cli.md)\n- [Figma reference sources and environment variables](./docs/figma.md)\n- [Report format and artifacts](./docs/report.md)\n- [Agent integration guide](./docs/agent-integration.md)\n\n## Agent Integration\n\nReusable agent assets live in [`agents/`](./agents). The main file is [`agents/SKILL.md`](./agents/SKILL.md).\n\nIf you want AI agents to use `peye` correctly, you should add or vendor [`agents/SKILL.md`](./agents/SKILL.md) into your agent runtime or skill registry. That file tells the agent:\n\n- when `peye` should be used\n- how to run `peye compare`\n- how to interpret `report.json`\n- how to structure compare -> inspect -> fix -> rerun loops\n\nRecommended setup:\n\n- install the CLI so the `peye` executable is available in `PATH`\n- copy or vendor [`agents/SKILL.md`](./agents/SKILL.md) into the agent environment\n- keep the skill file versioned alongside the CLI version you use\n- adapt the file if your runtime expects different metadata or frontmatter\n\n[`agents/openai.yaml`](./agents/openai.yaml) is included as a small example of agent-facing metadata and prompt wiring.\n\nImportant: the published npm package installs the CLI, but it does not install the agent skill files for you. If your workflow depends on AI agents, you need to add [`agents/SKILL.md`](./agents/SKILL.md) yourself.\n\n## Development\n\n```bash\npnpm check\n```\n\nThis runs formatting checks, type checking, linting, tests, and the production build.\n","readmeFilename":"README.md"}