spark-e2e
v0.7.0
Published
VLM + DOM dual-engine visual audit for the web — screenshot in, findings out. Works with Playwright CLI and Claude Code.
Maintainers
Readme
spark-e2e
VLM + DOM dual-engine visual audit CLI. Does NOT control the browser — Playwright CLI handles that. spark-e2e reviews screenshots and DOM dumps: PNG in, Findings out.
Install
# Global install (recommended)
npm install -g spark-e2e
# Or on-demand via npx
npx spark-e2e <command>Quick Start
# 1. Interactive setup — pick provider, configure VLM, install skills
spark-e2e setup
# 2. Verify your setup
spark-e2e doctor
# 3. Take a screenshot with Playwright CLI
playwright-cli open --browser=chrome
playwright-cli goto http://localhost:5173/dashboard
# (screenshot via page.screenshot() in a script)
# 4. Review the screenshot with spark-e2e
spark-e2e review --screenshot /tmp/shot.png --mode strictCommands
Visual Analysis
| Command | Description |
|---|---|
| spark-e2e review --screenshot <path> | Comprehensive UI audit — VLM-powered, returns findings JSON |
| spark-e2e assert "<condition>" --screenshot <path> | Single-condition pass/fail check |
| spark-e2e test "<expectations>" --screenshot <path> | Multi-expectation verification |
| spark-e2e inspect "<prompt>" --screenshot <path> | Free-form VLM analysis |
Review modes: --mode light (1 VLM call) or --mode strict (N parallel dimension-specific calls → intersect). Use --dom <path> for DOM cross-validation.
DOM Analysis
| Command | Description |
|---|---|
| spark-e2e dom-lint --dom <path> | Deterministic rule checks (token compliance, a11y) |
| spark-e2e dom-get <ref> --dom <path> | Element property lookup by @ref |
Built-in lint rules: no-hardcoded-px, no-raw-colors, font-weight-audit, token-usage, missing-alt, empty-button. Rules are powered by dom-rules.json (generated by /spark-e2e-init).
Baselines
| Command | Description |
|---|---|
| spark-e2e baseline save --name <name> --screenshot <path> | Save screenshot as reference |
| spark-e2e baseline compare --name <name> --screenshot <path> | VLM-powered semantic diff |
| spark-e2e baseline list | List saved baselines |
| spark-e2e baseline delete --name <name> | Delete a baseline |
Baseline compare sends both screenshots to VLM for semantic comparison — "layout shifted 20px" not "342 pixels changed".
Setup & Maintenance
| Command | Description |
|---|---|
| spark-e2e setup | Interactive wizard — VLM config, skill installation |
| spark-e2e doctor | Diagnose environment (Node, API key, AESTHETICS.md, dom-rules.json) |
| spark-e2e update | Migrate data from older versions (--dry-run to preview) |
Architecture
Playwright CLI / MCP spark-e2e
───────────────────── ─────────────────────
browser control VLM visual analysis
navigation, click, type deterministic DOM lint
screenshot, DOM dump semantic baseline diff
page interaction AESTHETICS.md injection
credential-safe promptsTwo review engines:
| Engine | What it checks | How | |--------|---------------|-----| | VLM review | Visual issues (layout, color, typography, spacing, charts) | Screenshot → VLM analysis | | dom-lint | Deterministic rules (token compliance, font-weight, a11y) | DOM dump → rule matching |
Use both — they complement each other. VLM catches what the eye sees; dom-lint catches what only the DOM knows.
Configuration
Setup Wizard (recommended)
spark-e2e setupManual — .spark-e2e.yaml
vlm:
provider: openai-compat
api_key: "${SPARK_E2E_API_KEY}"
base_url: "${SPARK_E2E_BASE_URL}"
model: gpt-4o
thinking_budget: 4000
viewport:
width: 1600
height: 1200
prompts:
strictness: standard # standard | strict | relaxedEnvironment Variables
export SPARK_E2E_API_KEY="sk-..."
export SPARK_E2E_BASE_URL="https://api.openai.com/v1"
export SPARK_E2E_MODEL="gpt-4o"
export SPARK_E2E_THINKING_BUDGET="4000"Config priority: CLI args > env vars > YAML > defaults.
Skills as Slash Commands
spark-e2e ships 2 Claude Code skills:
| Skill | What it does |
|---|---|
| /spark-e2e | Playwright-first visual review workflow |
| /spark-e2e-init | Scan codebase → AESTHETICS.md + dom-rules.json |
Install via spark-e2e setup.
init → review loop
Code changes → /spark-e2e-init rescans → AESTHETICS.md + dom-rules.json update
↓
spark-e2e review auto-uses latest specs
↓
VLM has grounded expectations ("expected: #F0824C from AESTHETICS.md")
↓
dom-lint uses same source ("expected: font-weight 500 from dom-rules.json")Security
- No credentials in prompts: VLM is instructed never to transcribe passwords, API keys, or tokens
- No browser control: spark-e2e never launches a browser — no risk of capturing passwords on screen
- Env var interpolation: Use
${VAR}for secrets, never hardcode - File permissions:
~/.spark/plugin/e2e/.envischmod 600(owner-only)
Source Layout
src/
├── cli.ts Commander, 9 subcommands
├── config.ts 5-layer config (cli → env → yaml → legacy → default)
├── baselines.ts Baseline CRUD
├── schemas.ts Shared types (DomDump, Findings, etc.)
├── migrate.ts Versioned migration engine
├── setup.ts Interactive setup wizard
├── engine/
│ ├── review.ts VLM review (light/strict, DOM cross-validation)
│ ├── dom-lint.ts Deterministic DOM rule checker
│ ├── dom-get.ts Element lookup by @ref
│ ├── rules.ts Rule registry + dom-rules.json loader
│ └── prompts/ Structured review prompts (safety, review, assert, etc.)
└── vlm/
└── openai-compat.ts OpenAI-compatible providerLicense
MIT
