Mirror — a deterministic SVG perception eye for LLM agents

Mirror renders SVG in a real browser and reports what is actually where — in grid cells and W3C color names, with prose and structured output — and it never guesses. Spatial layout constraints become unit tests. And every tool description is a claim the server proves about itself. Built for agents that can't afford to hallucinate coordinates.

What is this?

When an LLM agent edits an SVG, how does it know whether the change worked? Today it either guesses from the source text (and hallucinates positions, because layout is a render-time property, not a source property) or it takes a screenshot and guesses from pixels (and burns tokens on a vision round-trip that still can't name a color or address a region precisely).

Mirror is the third option: a measuring eye. It is a sensory organ for LLMs, not a tool with a purpose. It perceives and measures; it never interprets, decides, or acts — the brain (the LLM or you) does that. The eye has three tissues:

Because the measurement runs in a real browser engine, Mirror sees what the browser sees — including things the SVG source never tells you.

Killer demo: the perceive → constrain → correct → compare loop

A cold agent (no source code, MCP only) built a 17-element mission-control panel and verified it to an exact stop-condition. Here is the loop, with real outputs from that session:

# 1 — INSPECT: see the layout in LLM grammar (no constraints checked yet)
inspect(svg)
  → scene: 16 elements, grid 16×10, canvas_validity: valid
    e.g. { id: "led-ok", tag: "circle", cell: "B3", color: "lime" }
    colors come out as W3C NAMES, never hex.

# 2 — CONSTRAINTS: ask the vocabulary (it is finite and closed)
constraints()
  → 11 types. RIGHT-OF / BELOW deliberately do NOT exist
    (use LEFT-OF / ABOVE with swapped operands).

# 3 — ANALYZE: turn layout intent into unit tests
analyze(svg, ["#title CENTERED-IN #frame", "#led-ok ABOVE #led-warn", ...16 constraints])
  → PARTIAL: 2 unchecked SUBJECT_TIME_VARIANT
    "#beacon has an animated r → not measurable; geometrically satisfied @t0 (bbox …)"
    # the eye refuses to guess about an animated value. It says so, with a reason code.

# 4 — fix, re-analyze until PASS (convergence is tracked, not vibes)
analyze(svg_v3, [...], previousIssueCount: N)
  → PASS  (corrections == [] && unchecked == [] && canvas_validity == valid && diff == [])

# 5 — SNIPER LOOP: pin a baseline, edit, catch regressions in one call
bookmark("panel-pass", analysisId)
compare(sabotaged_svg, [], "panel-pass")
  → FAIL: FARBÄNDERUNG orange→crimson  +  VERSCHOBEN D7→H8
    with ready-to-apply fixes: { x: 262→182, y: 372→324 }
    # exactly the two injected faults. Nothing more, nothing less.

The agent's verdict, verbatim: "In 13 calls it never once guessed, lied, or made me guess. analyze landed on the first try. Lost diagnostic loops: 0." — 8.5/10.

Features — the honesty axes

Mirror's differentiator is not what it measures but that it is honest about what it cannot.

The rule, stated once: the eye measures gaps; the brain prescribes corrections. Mirror never clamps, smooths, or invents a value to please you. If it can't measure, it says not_measurable.

Why not screenshots?

A whole field exists for "show the agent the UI" — screenshot MCPs, SVG rasterizers, pixel-diff regression (Percy, BackstopJS, Playwright snapshots), accessibility-tree snapshots. They all share one limit: they hand the agent pixels (or structure) and the agent still has to guess. A screenshot can't be addressed (which region?), can't name a color precisely, can't tell you whether an element is measurably inside a frame or just looks inside, and can't say "I don't actually know — this is animated." (A 24-source competitive scan found no tool that combines LLM-grammar SVG perception, declared honesty axes, and proven tool descriptions.)

Mirror replaces the pixel guess with measured render truth in a grammar LLMs read natively — no image modality, no vision round-trip, no hallucinated coordinates.

Quickstart

Requirements: Node ≥ 18. Mirror renders in real Chromium via Playwright, so a browser binary is needed once.

# install the Chromium engine Mirror measures with (one-time)
npx playwright install chromium

Run as an MCP server — add to your client's MCP config (Claude Desktop, etc.):

{
  "mcpServers": {
    "vector-mirror": {
      "command": "npx",
      "args": ["-y", "vector-mirror"]
    }
  }
}

On initialize, the server hands your agent a full Quickstart: the workflow, the constraint grammar, four verified gotchas, a glossary, and the exact stop-condition — so a cold agent is productive with zero source reading (this is measured; see The Proof).

First call to try: vector_mirror_inspect with an SVG string → you get the scene in grid grammar. Then vector_mirror_constraints for the vocabulary, then vector_mirror_analyze.

The Proof

Mirror does not ask for trust; it earns it. Three pieces of evidence:

1 · Cold-consumer love metric

A cold agent (MCP only, no source) built and verified a 17-element panel in 13 tool calls with 0 lost diagnostic loops, scoring 8.5/10 with the reason "never once guessed, lied, or made me guess." The built-in sabotage test caught exactly the two injected faults, with ready-to-apply fix numbers. The one point deducted was an honestly-reported design seam — Mirror reports its own weaknesses too.

2 · Multi-model convergence

13 cold agents across 5 model families (Haiku, Sonnet, Opus, Gemini, Codex) consumed the server independently. Median love 8.0/10; substantive lost loops near zero. Agents guided through the MCP layer did not fall into the traps that un-guided raw-API users did — the guidance layer measurably works.

3 · Machine-proven tool descriptions + anti-circular self-test

Every sentence the server ships — tool descriptions, quickstart, glossary — is projected from one source (src/interface/claims.js) and is a probe-backed claim (tests/relais_red/). A mutation in the shipped text turns a test red. On top of that, a 5-fixture self-test runs anti-circularly — against spec-derived expected values, never against the server's own stored output. As one consumer put it: "that is the sentence that actually justifies trust."

Determinism: byte-identical input (sanitized DOM, time, selector) → byte-identical output, for a pinned Chromium engine. Verified by a dedicated determinism suite (including an anti-false-green mutation) and property-based fuzzing (fast-check).

Architecture — three tissues, one organ

                    ┌─────────────────────────────────────────┐
   raw SVG  ──────▶ │  RETINA   sanitize → real Chromium       │  measured truth
                    │  (src/adapters/renderer, src/core)       │  (geometry, color,
                    │  hexagonal: core is import-free          │   visibility, paint)
                    └───────────────────┬─────────────────────┘
                                        ▼
                    ┌─────────────────────────────────────────┐
                    │  MOUTH    prose + structured             │  two projections
                    │  (src/adapters/emitter)                  │  of ONE truth
                    └───────────────────┬─────────────────────┘
                                        ▼
                    ┌─────────────────────────────────────────┐
                    │  PACKAGE INSERT   tool descriptions +    │  every claim
                    │  quickstart (src/interface/claims.js)    │  is proven
                    └─────────────────────────────────────────┘