Mermaid Renderer Switches from PNG to SVG: An Overlooked Quality Blind Spot

Automated tests say "pass," humans zoom in and say "blurry." The distance between these two things is often wider than we imagine.

A PNG That "Looks Fine"

The story starts in an ordinary way. To avoid spinning up a headless Chrome browser every time an AI Agent needed to draw a flowchart, a developer wrote a Mermaid renderer from scratch. The first version was straightforward: render at a fixed width, return a base64-encoded PNG.

Everything was normal during testing — bytes decoded correctly, image dimensions matched expectations, test cases were all green. By the standards of automated testing, this feature was "done."

The problem showed up in a scenario automated tests can never cover: someone pasted the generated flowchart into a slide deck, then zoomed in. The text was blurry. Not corrupted, not missing — just rasterized to a resolution where "you can't tell there's a problem unless you zoom in."

PNG (Portable Network Graphics) is a pixel-grid-based bitmap format. An image consists of a fixed number of pixels, each recording color information. It uses lossless compression and is suitable for storing images that require precise pixel-level fidelity, but its resolution is locked in at generation time. When the image is enlarged, software can only interpolate between existing pixels, causing edges and text strokes to become blurry and jagged. This blur is not file corruption but an inherent property of raster formats: they record "what each point looks like at a given size," not "what lines and shapes the graphic itself is made of." For this reason, PNG has a natural ceiling on sharpness in scenarios requiring scaling, high-resolution printing, or high-magnification viewing.

In this case, the developer chose to render at a fixed width and return a base64-encoded PNG. Base64 encoding simply converts binary image data into a character sequence that can be transmitted over text protocols — it doesn't change the image's resolution or sharpness. So all automated tests passed — bytes decoded correctly, dimensions matched expectations — but the "fixed width" premise had already silently determined the sharpness ceiling of this image when zoomed in.

"Rendering Correctly" and "Rendering Well" Are Two Different Things

The value of this story isn't in the technical difference between PNG and SVG — that's common knowledge. What's truly worth reflecting on is: automated tests verify "whether an image was returned," not "whether a human can read the labels on it."

The developer's own summary is remarkably precise: "renders correctly" and "renders well" are different acceptance criteria, and the latter is typically completely invisible to the automated test that declares the former as passing.

This isn't one person's oversight. In Agent toolchain development, output is often treated as an intermediate artifact — as long as the downstream can parse it, it's fine. But when the output ultimately passes through human eyes, a crack opens between "parseable" and "readable."

The Fix: SVG by Default, PNG Demoted to an Option

The eventual fix is neither complex nor trendy: change the default output format to SVG.

The effect is immediate — vector graphics don't lose fidelity at any zoom level, file sizes are actually smaller, and charts stay sharp at any magnification. PNG wasn't removed, just changed from default to optional: email attachments, some chat clients, and legacy pipelines still need raster images, and passing an explicit format parameter gets you one.

The change is essentially just flipping one parameter's default value, but it turns a failure mode that was once exposed to all users as default behavior into an opt-in option that only triggers when actively chosen.

This renderer has been packaged and released, enabling Mermaid-to-image conversion without a browser stack, at x402.freeq.one.

SVG (Scalable Vector Graphics) is an XML-based vector graphics format. It doesn't record the color of each pixel; instead, it defines graphics using mathematically described lines, curves, paths, and text elements. During rendering, the display engine computes them in real time at the current size, so edges stay sharp and text stays crisp no matter how much you zoom in. Because it stores geometric descriptions rather than pixel arrays, the same simple flowchart typically results in a smaller SVG file than a high-resolution PNG. Another advantage of SVG is that text often remains selectable, searchable real text rather than pixels "burned" into the image. Its limitations are that it's unsuitable for continuous-tone content like photos, and different rendering engines have subtle differences in support for complex features. For flowcharts, diagrams, and schematics — graphics composed of lines and text — vector formats are almost always the better choice.

This also explains why changing the default format from PNG to SVG is a high-leverage change: it adds no new features, yet it stops the most common usage path — pasting into slides or documents and zooming in — from triggering the blur failure mode.

Implications for AI Agent Tool Development

This case reflects a pervasive quality-control blind spot in Agent toolchains.

Tests assert existence; users perceive quality. Automated tests are good at answering "does the function return a value of the expected type," but they're nearly powerless to answer "is the returned value good enough in real usage scenarios." Resolution, font readability, color contrast — these dimensions are inherently difficult to cover with assertions.

Format choice should match the consumption scenario. Agent-facing APIs tend to return the most generic format, but "generic" doesn't equal "appropriate." When output may enter human view — presentations, documents, reports — vector formats are almost always the safer choice. Choosing defaults is essentially about pre-setting a hard-to-get-wrong path for most users.

Defaulting to a failure mode is hidden technical debt. Setting low-quality output as the default means distributing risk across all users, and only those who happen to zoom in will discover it. Making it optional hands the choice back to callers who know what they need.

A one-parameter change solves not a performance problem, not an architecture problem, but the cognitive gap between "we thought we tested it" and "the user actually looked at it."

One-line Summary

Automated tests verified the image could be generated, but only after a human zoomed in did the blurry text become apparent — the default format should change from PNG to SVG.

Paragraph Summary

The article tells a real case of a Mermaid renderer: to avoid headless Chrome, the developer implemented rendering from scratch, with the first version outputting fixed-width base64-encoded PNGs, and all automated tests passing. But when users zoomed in, the text was blurry. The root cause is that the tests asserted "whether an image was returned," not "whether a human can read it" — "renders correctly" and "renders well" are two different acceptance criteria. The fix was to switch the default output to SVG, leveraging vector graphics' zoom-invariant sharpness, while keeping PNG as an explicit option for scenarios like email attachments that still need raster formats. The author draws implications for Agent tool development: tests excel at verifying existence rather than quality, format choice should match the consumption scenario, and defaulting to low-quality output is a hidden form of technical debt.