Related Pages

Related topics: System Architecture & Deterministic Pipeline, MCP Tools Reference & WordPress Integration

Overview, Installation & Quick Start

Project Overview

Visionaire Engine is an open-source browser automation engine designed for AI agents and LLM-driven workflows. It exposes a deterministic tool surface (22 tools as of v0.6.2) that can be invoked by language models to interact with a real Chrome instance. The engine is built with a strong reliability focus, validated against a 24-case seeded-bug benchmark and a 277-test suite that exercises real browser behavior rather than mocks.

The project is licensed under Apache-2.0, granting unrestricted use including commercial deployments and an explicit patent grant. Source: README.md:1-40.

The engine is delivered as a TypeScript package with a single public entry point, intended to be embedded into agent runtimes, MCP servers, or custom orchestration layers. Source: src/index.ts:1-30.

Installation

Two primary installation paths are supported:

1. Containerized run (recommended for evaluation)

A Dockerfile is shipped at the repository root, allowing the engine to start with a single command. The image bundles a compatible Chrome build and the runtime required to drive it. Source: README.md:42-70.

docker build -t visionaire-engine .
docker run --rm -p 3000:3000 visionaire-engine

A glama.json manifest is included for registry introspection, so the build can also be discovered and pulled via compatible registries without manual cloning. Source: README.md:55-65.

2. Local Node.js install

The package is consumable as a standard Node module. Dependencies and scripts are declared in package.json. Source: package.json:1-50.

npm install
npm run build
npm start

The TypeScript entry point is src/index.ts, which re-exports the public API surface and the tool registry. Source: src/index.ts:1-15.

Quick Start

A runnable demonstration is provided at scripts/demo.ts. It boots the engine, registers the default 22-tool set, and executes a representative browser task end-to-end against a local Chrome instance. Source: scripts/demo.ts:1-40.

npx ts-node scripts/demo.ts

For LLM-backed usage, the recommended path is to connect the engine to a Claude-compatible client. The integration contract — including tool schemas, message framing, and streaming behavior — is documented in docs/clients.md. Source: docs/clients.md:1-30.

import { Visionaire } from "visionaire-engine";

const engine = await Visionaire.launch({ headless: true });
const result = await engine.invoke("navigate", { url: "https://example.com" });
await engine.close();

The tool surface is intentionally small and stable. Each tool has a JSON Schema definition that maps directly onto the function-calling format used by Claude and other frontier models, so no adapter layer is required for the most common case. Source: src/index.ts:20-45.

Architecture at a Glance

The engine follows a layered design that separates protocol-facing concerns from low-level browser control:

flowchart LR
    A[LLM Client<br/>Claude / MCP] --> B[Tool Registry<br/>22 tools]
    B --> C[Engine Core<br/>src/index.ts]
    C --> D[Chrome Driver]
    D --> E[Real Chrome Instance]
    C --> F[Benchmark Harness<br/>24 seeded bugs]
    C --> G[Test Suite<br/>277 tests]

• Tool Registry — the 22 callable operations exposed to agents; each entry carries a JSON Schema and an executor binding. Source: src/index.ts:25-60.
• Engine Core — orchestrates session lifecycle, request validation, and error normalization. Source: src/index.ts:30-55.
• Chrome Driver — translates high-level tool calls into Chrome DevTools Protocol commands. Source: README.md:72-90.
• Benchmark Harness — the 24-case seeded-bug suite that gates releases on regression-free operation. Source: README.md:30-40.

What to Read Next

• Tool Reference — full enumeration of the 22 tools and their parameters.
• Clients — wire-level details for Claude and MCP integrations.
• Benchmarking — how the seeded-bug suite is structured and how to extend it.

Related Pages

Related topics: Overview, Installation & Quick Start, MCP Tools Reference & WordPress Integration

System Architecture & Deterministic Pipeline

visionaire-engine is structured around a deterministic rendering-analysis pipeline that turns a live browser DOM into a sequence of reproducible computed-style and layout outputs. The engine is split into small, single-purpose modules under src/engine/ that communicate through pure functions and shared types, ensuring that the same input (DOM snapshot + stylesheets) always produces the same numeric results.

Purpose and Scope

The architecture described in docs/architecture.md positions visionaire-engine as a deterministic CSS/style reasoning layer. Unlike conventional DOM libraries that expose side-effecting APIs, every engine stage is a pure function: given a node tree and a CSS environment, the output is stable across runs and platforms. This property is what enables the project's own self-tests — the 24-case seeded-bug benchmark and the 277 real-Chrome tests advertised for v0.6.2 — to assert exact numeric equality instead of fuzzy thresholds.

The scope is deliberately narrow: visionaire-engine does not own the browser. It consumes the DOM/CSS data that clients (Claude, MCP, CI runners, the bundled Dockerfile) feed into it, and it returns a fully-resolved, spec-faithful representation of what each element would render. Determinism is therefore a contract that lets downstream agents — AI assistants in particular — reason about styling without re-running the browser.

Engine Module Map

The pipeline is composed of five cooperating modules under src/engine/. Each owns one CSS sub-problem and exports pure helpers used by the orchestrator.

Source: src/engine/cascade.ts:1-40, src/engine/specificity.ts:1-30, src/engine/box-model.ts:1-35, src/engine/geometry.ts:1-30, src/engine/color.ts:1-30

The modules are intentionally stateless: there is no shared mutable store between them. The orchestrator wires inputs and outputs explicitly, which is what makes the pipeline replayable.

The Deterministic Pipeline Flow

When a request enters the engine it traverses the following stages in a fixed order. Each stage's output becomes the next stage's input, and no stage reads global state.

flowchart LR
    A[DOM + CSS Snapshot] --> B[Specificity]
    B --> C[Cascade Resolution]
    C --> D[Box Model]
    D --> E[Geometry & Stacking]
    E --> F[Color Normalization]
    F --> G[Canonical Render Tree]

1. Specificity — specificity.ts turns each selector into a frozen (a, b, c) tuple. Tuples are sorted lexicographically, and equality is total ordering so ties resolve predictably. Source: src/engine/specificity.ts:20-60
2. Cascade — cascade.ts walks rules in origin order, applies !important, and reduces the rule set to a single declared-value map per node. The function is referentially transparent. Source: src/engine/cascade.ts:40-90
3. Box Model — box-model.ts consumes the cascade output and emits four axis-aligned rectangles per element, taking box-sizing into account so border-box and content-box never collide. Source: src/engine/box-model.ts:35-80
4. Geometry — geometry.ts resolves positioning offsets, computes containing blocks, and assigns z-index ordering. It returns a stable list rather than mutating node objects. Source: src/engine/geometry.ts:30-70
5. Color — color.ts is the final normalization pass: every color value is parsed into a single {r,g,b,a} record, eliminating currentColor and named-color ambiguity before serialization. Source: src/engine/color.ts:30-65

The output is a Canonical Render Tree — a JSON-serializable structure where every property has been reduced to its final, browser-equivalent value. Because the tree is canonical, it can be hashed for the seeded-bug benchmark and diffed between runs.

Determinism Guarantees and Trade-offs

Determinism in visionaire-engine is enforced structurally rather than by test discipline alone:

• No I/O inside engine modules. All browser access lives outside src/engine/; modules accept plain data structures only. This is the precondition that lets the same code run unchanged under the Dockerfile (headless), under Claude/MCP clients, and inside the unit-test suite.
• Frozen comparators. specificity.ts exposes a comparator that produces a total order; there are no platform-dependent tie-breakers. Source: src/engine/specificity.ts:60-95
• Color canonicalization. color.ts collapses all syntaxes to RGBA before the render tree is emitted, so downstream tools never need to re-parse colors. Source: src/engine/color.ts:65-100
• Box-model purity. Padding, border, and margin are computed against already-resolved sizes; the module never reads from layout side effects. Source: src/engine/box-model.ts:80-120

The trade-off is explicit in docs/architecture.md: visionaire-engine trades raw rendering speed for reproducibility. Any change to the cascade order, specificity comparator, or color grammar is a breaking change for the benchmark and must ship with regenerated fixtures.

How Clients Consume the Pipeline

The 22 tools documented for v0.6.2 are thin facades over this pipeline. Each tool selects a subset of the five stages and exposes the Canonical Render Tree in a form convenient for an agent (e.g., "explain why this element is red" calls cascade + color; "describe layout" calls box-model + geometry). Because every tool reuses the same pure stages, two tools that ask the same question always receive the same answer — a property the community has leaned on for AI-driven style debugging. Source: docs/architecture.md:1-60

This uniform pipeline is also why the glama.json introspection manifest can advertise the engine's capabilities statically: the set of stages, and therefore the set of tools, is closed and known at build time.

Related Pages

Related topics: System Architecture & Deterministic Pipeline, Deployment, Security, Benchmarking & Extensibility

MCP Tools Reference & WordPress Integration

The visionaire-engine exposes a set of Model Context Protocol (MCP) tools that allow LLM clients (Claude, Cursor, etc.) to drive a real Chrome instance and inspect, navigate, and modify web pages. A specialized subset of these tools targets WordPress sites, letting agents authenticate, read content, and interact with the admin dashboard through the same protocol surface.

The current release (v0.6.2) ships 22 tools verified by 277 real-Chrome tests and a 24-case seeded-bug benchmark, and the project is distributed under Apache-2.0 with a patent grant.

Tool Categories

Tools are grouped by the kind of page state they observe or mutate. The four core source files listed for this page map to four fundamental categories.

Page Introspection

page_snapshot captures a structured representation of the current document so an agent can reason about it without parsing raw HTML. According to src/tools/page-snapshot.ts, it returns the accessibility tree, viewport metadata, and a textual map of interactive regions. Source: src/tools/page-snapshot.ts.

page_origins enumerates the origins present in the active tab — useful for multi-frame pages, OAuth redirects, and cross-origin iframes. It powers authentication flows because WordPress logins frequently land on a different origin (e.g., public-api.wordpress.com) before redirecting back. Source: src/tools/page-origins.ts.

Element Location

find_elements resolves selectors to one or more DOM handles and returns stable identifiers (for example, data-vne-id attributes or ARIA-derived refs) that can be referenced by follow-up calls. Source: src/tools/find-elements.ts. The handle format is the contract that makes later tools idempotent — clients should store the handle returned here and reuse it instead of re-querying.

node_at_point answers the inverse question: given a viewport coordinate, return the underlying DOM node. This supports screenshot-based agents that point at a rendered position and need the semantic target behind it. Source: src/tools/node-at-point.ts.

Interaction and Mutation

Beyond the four listed, the remaining ~18 tools cover click, type, scroll, navigate, evaluate JS, wait-for-condition, and upload. Their signatures are documented uniformly in docs/tools.md, which is the canonical reference clients should load before calling any tool. Source: docs/tools.md.

Typical Tool Workflow

flowchart LR
    A[page_snapshot] --> B{Element known?}
    B -- No --> C[find_elements]
    B -- Coordinate only --> D[node_at_point]
    C --> E[click / type / evaluate]
    D --> E
    E --> F[page_snapshot again]
    F --> G[page_origins if redirected]

Each arrow represents a tool call. The loop A → E → F is the agent's verify-after-act pattern: the engine never trusts a single observation, it re-snapshots after every mutation to confirm the DOM settled into the expected state.

WordPress Integration

WordPress sites — including *.wordpress.com, self-hosted installs behind /wp-admin, and WooCommerce fronts — receive a thin convenience layer documented in docs/wordpress.md. Source: docs/wordpress.md.

The integration does not replace the generic tools; it composes them. A "log in" flow, for instance, is expressed as: page_origins to confirm the auth redirect target, find_elements to locate the username/password fields and submit button, type to fill credentials, then page_snapshot to verify the dashboard loaded and that the wp-admin chrome appears in the accessibility tree.

WordPress-specific parameters the engine understands:

• wpContext: one of admin, editor, frontend, login — inferred from the snapshot, but overridable by the client.
• nonce: WordPress REST nonces are surfaced in page_snapshot output so agents can call authenticated REST endpoints directly without scraping the HTML.
• postHandle: a shorthand that wraps find_elements plus a stable editor anchor, letting agents refer to a Gutenberg block by its block ID.

Clients should consult docs/clients.md (referenced in the v0.6.2 release notes) for adapter-specific examples when wiring visionaire-engine into Claude Desktop, Cursor, or a custom MCP client.

Reliability Notes

Two reliability guarantees come up repeatedly in the tool docs:

1. Determinism: every read-style tool (snapshot, origins, find, node-at-point) is pure with respect to the current page state — calling it twice yields the same handle shape as long as the DOM has not changed.
2. Round-trip safety: mutation tools echo the affected handle and the post-mutation snapshot hash so the client can detect mid-call divergence (e.g., a WordPress autosave rewriting the editor DOM).

These properties are what make the 24-case seeded-bug benchmark reproducible across releases.

See Also

• docs/tools.md — full tool reference, parameter schemas, return shapes.
• docs/wordpress.md — WordPress context helpers and REST bridging.
• docs/clients.md — per-client configuration (Claude, Cursor, custom).
• Dockerfile and glama.json at the repo root for one-command deployment and registry metadata.

Related Pages

Related topics: Overview, Installation & Quick Start, MCP Tools Reference & WordPress Integration

Deployment, Security, Benchmarking & Extensibility

This page consolidates the operational surface of visionaire-engine: how the project ships, how it is licensed and sand-boxed, how its correctness is measured, and how tool providers and LLM clients integrate with it. The focus is v0.6.2, the current Apache-2.0 release. Source: README.md:1-40

Deployment

The engine is delivered as a self-contained Node service that can either be started locally with npm start or run inside a hardened container with a single docker run command. The Dockerfile pins a Node base image, copies the compiled JavaScript output (no dev dependencies), and exposes the MCP/HTTP port used by the host application. Source: Dockerfile:1-30

A companion .dockerignore strips test fixtures, benchmarks, documentation, and editor metadata so that the published image only contains the production runtime. This keeps image size small and reduces the attack surface of what is shipped. Source: .dockerignore:1-20

The package.json scripts section exposes the operational entry points — start, build, test, and bench — and declares the runtime dependencies (Chrome DevTools Protocol client, MCP server, LLM SDKs). The bin entry produces the visionaire-engine CLI used by container orchestrators and CI. Source: package.json:1-60

TypeScript compilation is governed by tsconfig.json, which enforces strict mode and NodeNext module resolution; this guarantees that the shipped JavaScript matches the type-checked source of truth and avoids silent interface drift between tools and clients. Source: tsconfig.json:1-30

Security

v0.6.2 is published under the Apache-2.0 license, a change from earlier versions. This relicense includes the explicit patent grant of §3, giving commercial adopters an indemnity against contributor patent claims and clarifying that the code may be embedded in proprietary products. Source: LICENSE:1-40

The MCP server enforces a strict origin allow-list and rejects any tool call whose arguments do not match the JSON Schema published in glama.json. This schema-driven validation is what makes the 22 tools safe to expose to an LLM: every parameter has a type, an enum, and an upper bound before it ever reaches a browser tab. Source: glama.json:1-80

Browser isolation is delegated to a dedicated Chrome profile launched in headless mode with --no-sandbox-equivalent hardening for containerized runs; the engine never shares the host's user-data-dir. Auditing is performed through the Chrome DevTools Protocol over a loopback websocket, so no browser state persists between sessions.

Benchmarking

Quality is measured by two orthogonal harnesses configured in vitest.config.ts:

Source: vitest.config.ts:1-40 npm test runs both suites against a transient Chrome instance, which means no flaky mock services are needed. Source: package.json:40-70

The seeded-bug set is recorded alongside the test fixtures and is treated as a regression contract: any change that makes a previously-detected bug invisible will fail CI immediately.

Extensibility

Adding a tool is a three-step process: implement a class in src/tools/, register it with the central ToolRegistry, and rerun npm run bench so that the benchmark suite records the new behavior. The glama.json file is auto-generated from the registry at build time and provides the schema that downstream clients (Claude, MCP-aware IDEs, custom agents) introspect to discover capabilities. Source: glama.json:1-80

LLM client adapters live in src/clients/ and are documented in docs/clients.md, which lists the supported transports (Anthropic, OpenAI-compatible, local llama.cpp, and MCP-native agents) together with the recommended streaming and tool-use configuration. Source: docs/clients.md:1-60

Because the registry is the single source of truth, the same 22 tools are exposed uniformly regardless of which client invokes them, and new clients are added by implementing a thin transport adapter without touching the tool implementations themselves.

Doramagic Pitfall Log

Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: v0.6.1 — the pixel-perfect release
• User impact: Upgrade or migration may change expected behavior: v0.6.1 — the pixel-perfect release
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.6.1 — the pixel-perfect release. Context: Observed when using node
• Evidence: failure_mode_cluster:github_release | https://github.com/mi60dev/visionaire-engine/releases/tag/v0.6.1

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/mi60dev/visionaire-engine

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/mi60dev/visionaire-engine

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mi60dev/visionaire-engine

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/mi60dev/visionaire-engine

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/mi60dev/visionaire-engine

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mi60dev/visionaire-engine

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/mi60dev/visionaire-engine

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: Developers should check this maintenance risk before relying on the project: v0.6.2 — Apache-2.0
• User impact: Upgrade or migration may change expected behavior: v0.6.2 — Apache-2.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v0.6.2 — Apache-2.0. Context: Observed when using docker
• Evidence: failure_mode_cluster:github_release | https://github.com/mi60dev/visionaire-engine/releases/tag/v0.6.2

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using visionaire-engine with real data or production workflows.

• v0.6.2 — Apache-2.0 - github / github_release
• v0.6.1 — the pixel-perfect release - github / github_release
• Configuration risk requires verification - GitHub / issue