render-verify

name	render-verify
description	Verify a rendered visual artifact actually says what it was supposed to say — open it, read its console errors, walk a failure catalog, and check it against the claim it was meant to carry. Works on charts, generated HTML reports, SVG, dashboards, diagrams, and any other output meant to be looked at. Use after render_chart / create_chart_view, after editing a post-Flint Vega-Lite spec, and before committing any generated HTML/SVG/PNG. Satisfied by the host's built-in browser tools or by the optional playwright MCP server.
lastReviewed	2026-07-25T00:00:00.000Z

render-verify: look at what you rendered

Why this skill exists

A visual artifact can be technically valid and still tell the wrong story. A chart with a collapsed axis, a merged color scale, or an empty data binding renders cleanly. So does a report whose images 404, whose text is clipped, or whose stylesheet never loaded. No validator catches any of it. validate_chart proves a spec is well-formed, not that the picture is true. Only looking does.

This is the plugin's characteristic bug shape — see Known failure modes in the repo docs. Every other silent failure here is a config path; this one is a picture.

The rule: if you rendered it, opened it, or edited it, look at it before you say it is done.

Scope. The method below — open, read the console first, walk a catalog, check the claim — is general. It applies to charts, generated HTML reports, SVG figures, dashboards, diagrams, and printable output. Charts are the deepest-worked case because this plugin produces them, and their catalog is the longest; a shorter general catalog follows it.

When to invoke

Mandatory:

• After any post-Flint Vega-Lite edit. The flint-chart skill forbids sending an edited spec back to render_chart, so the MCP server's own validation no longer protects you. You are flying without instruments.
• Before committing generated HTML, SVG, or PNG. Inline specs fail silently.
• When the artifact is layered, faceted, multi-series, or multi-figure. Most failures below come from layer, scale, or layout interaction.

Recommended:

• After the first render of anything that will be shown to someone other than the person who asked for it.
• Whenever you changed the data binding or the page structure, not just styling.

Skip:

• Single-layer chart, small embedded data, spec unchanged since a render you already looked at.
• The user is iterating rapidly on color or title only.

The failure catalog — charts

These render without error. Check each one explicitly — the list is the point of the skill, not the tooling.

Failure	What you see	Usual cause
Empty binding	Axes, gridlines, legend — and no marks	Data ref resolved to nothing. A chart with no data still looks like a chart. Rule out a render race first — see capability 5 in Step 1
Collapsed scale	Everything squashed into a fraction of the plot area	One layer forced zero: true (or a quantitative axis) into a shared scale
Merged color scale	A mark is the wrong color for its meaning	Two layers' color scales resolved together. Fix with independent scale resolution, not by recoloring
Undefined category	A blank, null, or undefined row/tick on a categorical axis	Mis-encoded layer contributing to a shared categorical domain
Duplicate marks	Rows repeated, bars double-height	Missing dedup upstream — a data problem wearing a chart costume
Embedded totals	One bar dwarfs the rest; parts look flat	An aggregate level (all, Total) charted alongside its own parts
Double-scaled units	Percentages at 0–10000, or everything at 0.0x	A 0–100 rate tagged as Percentage and scaled again
Overplotting	A solid blob instead of a distribution	Too many marks, no opacity/jitter/binning
Right on sample, wrong on real	Looks perfect, means nothing	Verified against test rows, never against the actual dataset

The failure catalog — any rendered artifact

For generated HTML, SVG, dashboards, diagrams, and printable output. These also render without error, and a screenshot alone can look plausible.

Failure	What you see	Usual cause
Missing resource	A broken-image icon, a blank figure slot, an unstyled block	A 404 on an image, stylesheet, font, or script. The console names it — this is why Step 2 reads errors first
Unstyled content	Raw serif text, no layout, everything left-aligned	The stylesheet never loaded, or loaded after the capture
Clipped or overflowing text	Sentences cut mid-word, labels truncated, text escaping its container	Fixed heights, overflow: hidden, or a font substitution that changed metrics
Font substitution	Right words, wrong typeface; spacing subtly off	A web font failed to load and a fallback took over. Silent by design
Layout collapse	Columns stacked, panels overlapping, huge whitespace	The captured viewport hit a responsive breakpoint you did not intend
Below-the-fold content never checked	Everything visible looks fine	Only the viewport was captured. Scroll or capture full-page
Stale render	Your change is not there	Viewing a cached copy, an old build output, or a different file than you edited
Placeholder survived	Literal TODO, Lorem ipsum, {{value}}, undefined, NaN	A template slot never filled. Search the rendered text, not just the source

Step 1 — pick a verification capability

This skill names the capability, not a product. Work down this ladder and stop at the first rung that works. Do not install a second MCP server for a job the host already does.

1. The host's own browser capability — always try this first. If your tool inventory contains anything that opens a page and returns a screenshot or a page snapshot to you, use it. In VS Code Copilot these are the built-in browser tools; they open file:// with no flags, no browser download, and no configuration, and they were verified against this plugin's own demo. This rung costs nothing and has no security trade-off.
2. The optional playwright MCP server — fallback. Use when rung 1 is absent, or when rung 1 lacks console-error access and the defect you are chasing needs a cause rather than a symptom. On a terminal-only agent such as GitHub Copilot CLI there is no rung 1 at all — it has no browser, so this rung is the primary path, not the fallback. See Playwright MCP setup below. It carries real costs: a browser must already be installed, file:// needs --allow-unrestricted-file-access, and it writes artifacts into the working directory.
3. The human. Ask the user to open the artifact and describe what they see, or give them a specific checklist item to confirm. This is a legitimate outcome, not a failure — but it must be stated.

Never silently skip verification. If you reached rung 3, or if you have partial capability (see below), say so plainly in your report. An unverified chart described as verified is worse than an unverified chart.

Which capabilities you actually need

"Can open HTML" is not one capability — it is five, and hosts differ in which they provide. Establish what you have before interpreting what you see.

#	Capability	Needed for	If missing
1	Open a local file://	Reaching the artifact at all	Fall back to a render_chart PNG/SVG, or rung 3
2	Agent-readable output (screenshot or accessibility snapshot returned to you)	Steps 3–4	You are on rung 3 — the human is verifying, not you
3	Console-error access	Step 2 — finding the cause	You can still see symptoms; say that causes were not checked
4	Element-scoped or scrolled capture	Multi-figure artifacts	Verify one figure per page-load, or accept reduced confidence and say so
5	Wait-for / re-capture after render	Anything JS-rendered (Vega-Lite, ECharts)	See the false-positive warning below

[!WARNING] Capability 5 can manufacture a defect that isn't there. Vega-Lite and ECharts draw after page load. A screenshot taken too early shows an empty container — which is visually identical to the empty binding row in the failure catalog. Before diagnosing "empty binding", re-capture at least once and confirm the emptiness is stable. Diagnosing a race as a data bug sends the fix upstream into a spec that was never wrong.

Probe by doing, not by asking: attempt the action against the real artifact and observe the result. Tool names vary between hosts; outcomes do not.

Step 2 — open it and read the errors first

1. Open the artifact. For local files use the canonical absolute file:///… form.
2. Read the console errors before looking at the picture. This is the check that finds the cause rather than the symptom — a silently-failing inline Vega-Lite spec throws to the console while still rendering a plausible-looking page. With the Playwright server this is browser_console_messages at level error.
3. Then screenshot it.

Zero console errors plus a wrong-looking artifact means a spec, data, or layout problem. Console errors plus a right-looking artifact means you are probably looking at a stale render.

Step 3 — check the picture against the catalogs

Walk the chart table if it is a chart, and the general table for anything that is rendered as a page. Then, for multi-figure artifacts:

• Scroll each figure into view and capture it separately. A single full-page screenshot visually hides defects in unfocused figures.
• Check the axes have real domains — not [0, 0], not a collapsed range, no undefined ticks.
• Count the marks against what the data should produce.
• Search the rendered text for placeholders — TODO, undefined, NaN, {{, Lorem. Search what rendered, not the source that produced it.

Step 4 — check the claim, not just the render

Every artifact worth verifying exists to carry a claim. For charts that is the Big Idea from the chart-big-idea skill; for a report or diagram it is whatever the surrounding prose asserts. A correct render of a wrong claim is still a defect.

• Verify prose claims arithmetically against the plotted or tabulated values. If the caption says "less than a fifth of the noise", compute it. Order-of-magnitude overstatements in captions survive every automated check there is.
• Re-read the claim and ask whether the picture shows it. If the claim is about a gap and the eye goes to a trend, the chart type is wrong — go back to flint-chart §0.2, do not patch the styling.

Step 5 — report honestly

State which capability you used, that you looked, and what you checked. If you could not verify, say that instead. Never describe an unopened render as verified.

Playwright MCP setup

Fallback only — rung 2 of Step 1. Try the host's own browser capability first; if it can open the artifact and return a screenshot to you, you do not need this server. Measured against @playwright/mcp@0.0.78:

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@0.0.78",
        "--headless",
        "--isolated",
        "--browser",
        "msedge",
        "--allow-unrestricted-file-access"
      ]
    }
  }
}

Merge this additively into the existing server map — overwriting the file destroys the user's other servers, including flint. Same per-host path table as the flint-chart skill (.vscode/mcp.json for VS Code, .mcp.json for Claude Code, .cursor/mcp.json for Cursor, ~/.copilot/mcp-config.json with key mcpServers for Copilot CLI).

Why each flag

Flag	Why
--headless	No visible window; this is a verification pass, not a demo
--isolated	No persistent browser profile — keeps the user's real session out of it
--browser msedge	There is no bundled browser — Playwright drives an installed one by channel. Edge ships with Windows, which is where most heirs are; the upstream default (chrome) is frequently absent there. Override with chrome, firefox, or webkit where Edge is not installed — typically Linux
--allow-unrestricted-file-access	Required for file://. Without it navigation is blocked outright. See the security note below

Security note — read before enabling the file-access flag

--allow-unrestricted-file-access lets the browser read any file the user can read. That is acceptable for verifying local artifacts you just produced. It is not acceptable in combination with browsing untrusted web pages: a malicious page can attempt to drive the agent into reading local files and sending them out. Keep this server for local verification. If you need general web browsing, use a separate configuration without the flag.

Do not enable browser_run_code_unsafe workflows for verification. Screenshot and console access are sufficient; arbitrary code execution is not needed to look at a chart.

Housekeeping

The server writes artifacts (accessibility snapshots, screenshots) into the working directory. Add .playwright-mcp/ to .gitignore or they land in commits.

Do not pass a bare filename to browser_take_screenshot. A bare name like shot.png is written to the working-directory root, which is outside the ignored folder and shows up as an untracked file in the user's repo. Either omit filename entirely — the server then writes into .playwright-mcp/ — or give a path inside that folder. Verified 2026-07-25: a bare filename leaked into git status while the snapshot beside it did not.

Troubleshooting

Symptom	Cause	Fix
Access to "file:" protocol is blocked	Flag missing — the default blocks file:// navigation entirely	Add --allow-unrestricted-file-access
Browser distribution '<channel>' is not found	No bundled browser — the selected channel is not installed on this machine	Switch --browser to a channel that is present (msedge / chrome / firefox / webkit), or run npx playwright install <channel>
Server reports a version like 1.62.0-alpha-…	That is the underlying Playwright library version, not the @playwright/mcp package version	Do not pin against what the handshake reports
Tools never appear at all	Config in the wrong path or under the wrong top-level key	Same trap as flint — see the per-host table in the flint-chart skill
Untracked .playwright-mcp/ in git status	Working-directory artifacts	Gitignore it

Anti-patterns

• Declaring an artifact done because the tool returned success. The tool reporting OK means bytes were written, not that the picture is true.
• Trusting a batch edit's summary line. When a multi-edit call reports "1 succeeded, 1 failed", verify which one landed by inspecting the file before re-rendering. The visible change is often not the one that succeeded.
• One full-page screenshot for a multi-figure report. Defects hide in the figures you did not focus.
• Verifying against sample data only. The failure mode this skill exists for appears when real data meets the spec.
• Installing the Playwright server on a host that already has a browser capability. Redundant dependency, extra config surface, no gain. Rung 1 before rung 2, always.
• Diagnosing an empty chart before re-capturing. JS-rendered charts draw after load; one early screenshot is not evidence of an empty binding.
• Screenshotting without reading the console. The console usually names the cause — a 404'd image, a failed font, a thrown spec error — while the picture only shows the symptom.
• Fixing a data or chart-type problem with a style tweak. Recoloring a mark that is wrong because two scales merged hides the bug instead of fixing it.

Would Revise If

Revise this skill by 2026-10-25 (90 days) or sooner if:

• The host's built-in browser tools gain or lose console-error access. browser_console_messages is currently the main capability that justifies the optional Playwright server at all.
• A host appears whose canvas renders HTML for the user but returns nothing to the agent. Capability 2 in Step 1 assumes "renders" and "agent can read it back" usually travel together. A surface that splits them would make rung 3 the common case rather than the exception, and Step 5's honesty requirement the most load-bearing part of this skill.
• @playwright/mcp changes its file:// default. The security note and the flag table both assume navigation is blocked unless the flag is set.
• @playwright/mcp ships a bundled browser by default. The troubleshooting row about installed-Chrome-by-channel would then be wrong.
• A failure mode recurs that is not in either catalog above. The tables are the load-bearing content; extend them rather than adding tooling.
• The general catalog stays unused across several sessions. That would mean this skill is really chart-only in practice and the broader name overpromises — either narrow the name back or delete the general table.
• Verification is consistently skipped by users, indicating the step is too heavy and should collapse into the flint-chart render step instead of standing as its own skill.