visionaire-engine

Purpose

Visionaire Engine gives AI coding agents deterministic "vision" capability, solving the problem that agents "cannot see the rendered result" when modifying CSS. Agents often can only output CSS text and cannot see actual pixels, so they easily guess, misjudge, and get stuck in loops. Visionaire reads the live page and tells the LLM the exact winning rule, its file and line number, and why, enabling the agent to make the correct fix on the first try.

Main capabilities

• Cascade adjudication: Determine which CSS rule wins, explain the decisive reason other rules fail, and give honest and actionable editing guidance (such as WordPress's "Site Editor → Styles").
• Attribution and localization: Provide attribution at the file, line number, database entity, and component levels, following the honest ladder of "line > file > database entity > component > generated > unknown".
• Blast radius and scoped fixes: Report in explain_styles the impact scope of modifying a shared selector, recommend using scoped selectors, and avoid "changing one button but changing all buttons".
• Live fix loop: inject_css can experiment with fixes on the page, observe changes, and after convergence write to source once.
• Pixel-level inspection: check_alignment (group alignment/spacing rhythm/grid/pixel alignment audit) and pick_color (actual drawn pixel sampling + WCAG contrast adjudication).
• Interaction and timing: Event listener attribution, animation diagnostics, and interaction timelines with source attribution.
• Verification and proof: assert_visual (17 assertion syntaxes, PASS/FAIL adjudication with measured pixels and problem element uid, supporting rerunnable named suites), visual_diff (pixel diff comparison with a model or baseline, mapping diff regions to element uid), impact_preview (sandbox dry run), diagnose (ranking the culprits of "why it broke"), responsive_sweep (per-viewport adjudication matrix), capture_proof (before-and-after evidence package).
• verify-after-edit test framework: Through npx visionaire-engine init-harness connect hooks for Claude Code and Cursor, so the agent cannot end the turn claiming "fixed" without a verification record.

How to use

Requires Node ≥ 22.12 and installed Chrome/Chromium. It can be registered directly from npm to Claude Code, or run from a cloned repository. When using clients such as GitHub Copilot, Cursor, Claude Desktop, Google Antigravity, refer to docs/clients.md for configuration. It is recommended to run in the project root directory so the agent can access both the running site and the on-disk source code.

Basic flow:

1. connect { url: "https://your-site.com" } Launch Chrome; or { mode: "extension", url } use your own browser through the extension.
2. solve { intent: "why is the hero CTA blue instead of white", context: { element: ".hero .btn" } } route to a diagnostic plan and give a verdict-first answer: the winning rule and file:line, why each opponent failed, visibility/overlap reasons, and a NEXT step. element can be a uid, selector, or visible text. If the element cannot be determined, return a uid outline for selection.
3. All engine tools can be accessed through solve expert mode:solve { intent, tool: "inject_css", args: { uid: "e17", declarations: { color: "#fff" } } }. The scenario can be used to force a specific plan (such as "overlap-z-index").

Using your own browser: The Visionaire Bridge extension supports the Chrome family (full engine via chrome.debugger) and Firefox (lightweight engine via content script). Chrome: chrome://extensions → Developer mode → Load unpacked → extension/dist/chrome; Firefox: about:debugging#/runtime/this-firefox → Load Temporary Add-on → extension/dist/firefox/manifest.json. First connect { mode: "extension" } returns a one-time pairing code; paste it into the Visionaire popup to complete pairing (once is enough). After that, connect { mode: "extension", url } opens the page in the agent tab, or connect { mode: "extension" } Check your shared tab. localhost and *.test are pre-approved; other sites will ask first (allow once/always/deny). Windows + WSL is also supported.

Try without an MCP client: a CLI method is provided.

Verification loop: preview the blast radius of shared classes (impact_preview) -> minimal-change edit -> assert with assert_visual (or rerun a named suite_id), obtaining PASS/FAIL + actual measured pixels + problem element uid -> for FAIL use diagnose to get ranked culprits -> responsive_sweep scans viewport by viewport -> capture_proof packages before-and-after screenshots and verdict changes. Run from the project root npx visionaire-engine init-harness Integrate the included Claude Code hooks or Cursor rules.

Use cases

Suitable for developers using LLMs to participate in site design changes, vibe coders, and anyone who has LLMs modify the frontend in a loop. Especially suitable for design debugging that requires precise attribution (which rule, which file, which line), WordPress style source resolution, responsive verification, and post-fix verification.

Limitations

• The full engine supports only Chromium (CDP is the only way to obtain source locations of matched rules). Firefox gets a lightweight engine via an extension: CSSOM cascading and line numbers recovered from stylesheet source, no user-agent rules, no listeners or input simulation.
• @layer: ordering is accurate with and without layers, but ordering between two different layer chains is a deterministic proxy (CDP does not expose layer declaration order).
• Some dependent CDP fields (specificity, layers) are experimental; the engine feature-detects and falls back (e.g., using its own specificity parser), and contract smoke tests fail loudly when Chrome updates break the core protocol shape.
• Attach mode accepts only loopback DevTools endpoints.
• In the user's own browser, evaluate and resource-loading CSS are disabled; cookie/storage protocol methods are blocked.
• The project is free and open source; specific fees and pricing are not provided at this time.