DEV Community: mitsuru

fulgur-chart: deterministic SVG/PNG from Chart.js JSON, without JavaScript

mitsuru — Wed, 24 Jun 2026 12:49:28 +0000

A new member has joined the fulgur family.

fulgur-chart — a CLI that takes Chart.js v4-compatible JSON specs and renders deterministic SVG/PNG charts. No browser required.

https://github.com/fulgur-rs/fulgur-chart

Two things make it different: it doesn't spin up a browser, and for a fixed version, font, and rendering options, the same JSON input always produces byte-identical output.

This post covers why I built it, a timing coincidence that made me feel like I was on the right track, and how to use it.

Why I wanted graphs in PDFs

fulgur and fulgur-chart are built around one idea: AI agents should be able to generate documents that look good.

There are three steps to that argument.

First, Markdown isn't expressive enough. For client-facing reports, plain Markdown often undersells otherwise strong content.

Second, visual quality is persuasive. A well-formatted report lands differently than a wall of text.

Third — and this is the one I keep coming back to — in many business workflows, PDF carries more institutional weight than a Markdown file or a transient web page.

That authority has two dimensions. There's a cognitive one: PDFs read as "serious documents." Proposals, reports, invoices — the format itself signals credibility. And there's a technical one: PDF can support digital signatures, encryption, and archival profiles such as PDF/A. That's the ground flpdf covers, a pure-Rust PDF toolkit modeled on qpdf's workflow.

So the goal is always PDF, not HTML, not a web page. That's what fulgur is for.

And a polished report needs charts. But Markdown can't draw charts.

Which brings me to a problem I already knew was coming: the Chart.js library requires JavaScript to run.

fulgur has no browser and no JS runtime, so there was no path to running Chart.js directly.

The design choice: no JS engine

The obvious alternative was to embed a JavaScript runtime. I could either run Chart.js with a compatible Canvas implementation, or build a JavaScript renderer that consumes Chart.js-style specs and emits SVG directly. Both approaches can be browser-free, offline, and deterministic.

But I wanted fulgur-chart to remain a Rust-only, data-only pipeline, with no JavaScript runtime and a smaller behavioral surface to audit and maintain. So I chose to interpret a supported subset of Chart.js-compatible JSON directly in Rust.

fulgur's philosophy is built on five pillars:

No browser required — no Chromium, no WebKit, no headless anything. Single binary, fast cold starts.
Low memory footprint — designed for server-side batch processing. Won't eat your container's memory limit.
Deterministic output — same input → byte-for-byte identical PDF, every time.
Template + JSON data — HTML templates with JSON data for bulk generation. MiniJinja engine built in.
Offline by design — no network access. Fonts, images, CSS — everything explicitly bundled.

fulgur-chart inherits this posture. Accepting arbitrary plugin code or dynamic callbacks would make the behavioral surface harder to reason about and test. The static, data-only design keeps it auditable.

To make the output truly deterministic, I scoped down the input: arbitrary plugin code, callbacks, and animations are excluded. fulgur-chart is data-only and fully static.

Fonts are bundled too. Noto Sans JP is included so text rendering never depends on the host system. Change the machine and the output stays the same.

Good-looking output. Deterministic output. I chose to chase both.

As a side effect: charts committed to git never show spurious diffs, and re-generating in CI is always safe.

The day after I started designing it, Artifacts shipped

Now for the coincidence.

I committed the initial design document for fulgur-chart on June 17, 2026.

The next day — June 18 — Claude Code Artifacts was announced.

Artifacts lets Claude Code generate rich, interactive reports as outputs: PR walkthroughs, dashboards, security reports, cost analyses. Currently in beta for Team and Enterprise: the output is a live, interactive web page viewed in a browser.

When I saw it, my immediate reaction was: this is exactly the world fulgur is building toward.

The belief I'd been acting on — that Markdown isn't good enough, that visual quality matters, that AI agents should produce proper-looking documents — felt like it had just received an independent signal from Anthropic itself. The timing didn't prove the design, but it was encouraging.

The directions are different: Artifacts goes toward the Web, fulgur goes toward PDF. Authority, determinism, offline-first. But the underlying conviction is the same: good output matters, and Markdown isn't good enough.

The contrast actually sharpened fulgur's position rather than blurring it.

And for good-looking PDF reports, you need charts. That's what fulgur-chart is for.

Usage

Basic usage is simple:

# Generate SVG from a JSON spec
fulgur-chart render chart.json -o chart.svg

# PNG at 2x resolution
fulgur-chart render chart.json -o chart.png --format png --scale 2

# Pipe mode (use - for stdin/stdout)
cat chart.json | fulgur-chart render - -o - > chart.svg

# Batch: process multiple specs
fulgur-chart render specs/*.json --out-dir out/

# Specify dimensions and use strict mode
fulgur-chart render chart.json -o chart.svg --width 1024 --height 576 --strict

Key options:

--format svg|png
--width <px> / --height <px>
--scale <factor>
--font <path>
--out-dir <dir>
--dsl chartjs|vegalite
--strict

The input uses the familiar shape of a Chart.js v4 config. fulgur-chart implements a data-only, static subset: common chart data and selected options work, while callbacks, interactions, and arbitrary plugin code are intentionally excluded.

{
  "type": "bar",
  "data": {
    "labels": ["Jan", "Feb", "Mar"],
    "datasets": [
      { "label": "Revenue (k$)", "data": [120, 200, 150], "backgroundColor": "#36a2eb" }
    ]
  },
  "options": {
    "plugins": { "title": { "display": true, "text": "Monthly Revenue" } }
  }
}

Options like options.plugins.title work as expected. In CI, use --strict so unsupported options fail loudly instead of being silently ignored.

Supported chart types

QuickChart is the closest reference point in terms of input format and chart coverage. It can also be self-hosted; fulgur-chart makes a narrower bet on a single local binary, data-only input, no JavaScript runtime, and deterministic output.

As of v0.1.x, the supported chart types are:

Bar chart (vertical/horizontal — use options.indexAxis: "y" for horizontal)
Stacked bar chart
Line chart
Area chart
Pie chart / Doughnut chart
Scatter plot
Bubble chart
Radar chart
Mixed chart
Matrix / heatmap
Box plot
Gauge / Radial gauge
Progress bar chart (QuickChart-compatible)

The progress bar chart is worth calling out. It's a QuickChart original: datasets[0].data sets the bar values; an optional second dataset's data overrides the max per bar (default is 100). Percentage labels are on by default — set options.plugins.datalabels.display: false to hide them.

The --dsl vegalite flag also accepts a Vega-Lite subset if you prefer that format.

How it's implemented

Reproducing Chart.js's visual output without a browser is more work than it sounds.

Layout, axes, legends, text measurement — everything the browser was handling silently has to be done from scratch. Text measurement in particular is critical for determinism: if that drifts, the output drifts. Bundling Noto Sans JP and doing all measurement against that removes the environment as a variable.

For a fixed fulgur-chart version, font, dimensions, and output format, the output is byte-identical across runs and machines. You can verify this in CI:

fulgur-chart render chart.json -o first.svg
fulgur-chart render chart.json -o second.svg
sha256sum first.svg second.svg
# both hashes should match

Architecturally, there's a layered design: DSL frontend → intermediate representation (IR) → rendering core. Adding support for a new input dialect (Chart.js, Vega-Lite, or eventually others) means adding a frontend that maps to the IR, without touching the renderer.

Development is Rust + AI-driven: Claude Code with superpowers, following a brainstorm → plan → implement cycle. Same approach I've been using for fulgur core — I wrote about that workflow here.

Embedding charts into fulgur PDFs

The original motivation was getting charts into PDFs.

The workflow: render an SVG with fulgur-chart, embed it in HTML with <img>, then pass the HTML to fulgur. The examples/report.html in the fulgur-chart repo shows a working example.

Font consistency matters here. Bundle the same Noto Sans JP in fulgur, and chart text glyphs will match the rest of the PDF exactly — no font mismatch between chart labels and body text.

That closes the loop:

AI agent → deterministic PDF report, with charts, looking polished, offline.

Where it is now and what's next

As of June 2026, fulgur-chart is still v0.x — young, but the core chart types work.

The immediate roadmap includes a few gaps in the current implementation:

Value labels on radar chart axes, data labels for scatter/radar
Dual-axis mixed charts
Vega-Lite transform, aggregate, URL data sources (currently inline data.values only)
Font subsetting to reduce binary size

Longer term, I'm thinking about:

More chart types — expanding toward full QuickChart coverage
More input formats — Graphviz and others in QuickChart's scope
Jsonnet support — programmatic spec generation
Server mode — run as a persistent API, QuickChart-style
Agent skill — expose chart generation as a direct tool call for AI agents

The destination: QuickChart-equivalent coverage, browser-free, deterministic, and ready for AI agents to call directly.

Wrapping up

The fulgur family keeps growing:

fulgur — HTML → PDF
flpdf — pure-Rust PDF toolkit modeled on qpdf
fulgur-chart — deterministic chart generation

All of them are projects I intend to keep building for a long time.

If any of this sounds useful, give it a try.

https://github.com/fulgur-rs/fulgur-chart

Introducing fulgur: a blazing fast HTML-to-PDF engine in Rust — no browser required

mitsuru — Sat, 25 Apr 2026 10:03:22 +0000

fulgur — (noun, Latin) lightning, flash of lightning.

I've been building fulgur, an HTML-to-PDF engine written in Rust. No headless browser, no Chromium, no WebKit — just an HTML parser, a layout engine, and a PDF writer, glued together with a pagination layer.

The current numbers (v0.5.14, 200-page document):

190 ms end-to-end
57 MB peak memory
Byte-identical PDF output across runs

This post is the story of how it got there: why I started it, what it's built on, what it can do today, and how I've been working with AI tools to ship it as a solo project.

Why build yet another HTML-to-PDF tool?

For years, wkhtmltopdf was the default. It's now archived, and the WebKit version it bundles has been frozen for years. Modern CSS doesn't really land there.

The mainstream replacements all have tradeoffs:

Headless Chromium / Puppeteer / Playwright — gorgeous output, but you're shipping a browser. Cold start is slow, memory footprint is huge, and "just spin up Chrome in a container" stops being fun the moment you need to render thousands of PDFs a day.
WeasyPrint — solid CSS Paged Media support, but Python and not particularly fast on big documents.
Hosted services (Gotenberg, DocRaptor, etc.) — great until you can't send the data off-box, or until the per-PDF bill gets uncomfortable.

What I actually wanted was something that fit on the same server as my app, started instantly, and didn't blow up a Kubernetes pod's memory limit halfway through a 200-page report.

That's the niche fulgur is going after.

The "aha" moment: Blitz + Krilla

The unlock was realizing I didn't have to write a layout engine or a PDF writer from scratch. Two excellent crates already exist in the Rust ecosystem:

Blitz — an HTML rendering engine from the Dioxus project. It does HTML parsing, CSS style resolution, and layout (via Taffy and Parley). It's not a full browser — no JS runtime, no networking — which is exactly what you want for a PDF tool.
Krilla — a high-level PDF writing library. It hides the gnarly parts of the PDF spec behind a clean API: text, shapes, images, gradients, tagged PDF for accessibility, font subsetting, the works.

So the question became: can I write the glue between "Blitz says this box goes here" and "Krilla, please draw text at this coordinate" — plus a pagination layer that splits content across pages?

Turns out: yes. That glue is fulgur.

HTML / CSS
    │
    ▼
Blitz  ── DOM → style resolution → Taffy layout
    │
    ▼
DOM → Pageable conversion (Block / Paragraph / Image)
    │
    ▼
Pagination  ── split the Pageable tree at page boundaries
    │
    ▼
Krilla  ── draw each page → PDF Surface
    │
    ▼
PDF bytes

While I was at it, I needed @media print support for things like print-only stylesheets. So I sent PR #390 to Blitz and it got merged upstream. Huge thanks to the Blitz maintainers — fulgur literally wouldn't be feasible without their work.

Performance

Here's where it gets fun. After landing a font caching change (wrapping the loaded font database in Arc so we don't reload Noto Sans JP for every page), the numbers shifted from "okay" to "actually production-ready":

Document	Engine	Time (ms)	Peak Memory (MB)
Large (200 pages)	fulgur	190	57
Large	fullbleed	92	(n/a)
Large	WeasyPrint	2,650	213
Large	wkhtmltopdf	1,180	198
Medium	fulgur	20	22
Medium	WeasyPrint	516	74
Small	fulgur	10	18

Two things stand out:

Memory is the real story. 57 MB to render a 200-page document means you can run fulgur inside a normal-sized container without thinking about it. WeasyPrint and wkhtmltopdf use 3–4x more.
190 ms is fast enough that PDF generation stops being a background job. You can render on the request path for most documents.

Why isn't it even faster? The pipeline does a 2-pass render so that running headers/footers can show "Page X of Y" — page count needs to be known before laying out the page chrome. That cap is structural; I'd rather have correct page numbering than shave another 50 ms.

What v0.5.14 actually does

The version on Zenn was v0.3.0. A lot has shipped since:

Automatic page splitting with full CSS pagination control (break-before, break-after, break-inside, orphans, widows)
CSS Generated Content for Paged Media (GCPM) — page counters, running headers and footers, margin boxes
Built-in template engine — pass an HTML template + JSON data, get a PDF. Powered by MiniJinja.
Image embedding — PNG, JPEG, GIF
Custom font bundling with subsetting — TTF, OTF, TTC, WOFF2
PDF bookmarks auto-generated from h1–h6
PDF metadata — title, author, keywords, language
External CSS injection, page sizes (A4 / Letter / A3) with landscape, configurable margins

Quick CLI tour

Install via npm (no Rust toolchain needed):

npx @fulgur-rs/cli render -o output.pdf input.html

Or via Cargo:

cargo install fulgur-cli

Basic usage:

# Convert a file
fulgur render -o output.pdf input.html

# Pipe HTML in
cat report.html | fulgur render --stdin -o report.pdf

# Page options
fulgur render -o output.pdf -s Letter -l --margin "20 30" input.html

# Bundle fonts and CSS
fulgur render -o output.pdf -f fonts/NotoSansJP.ttf --css print.css input.html

Template + JSON

This is the part I'm most excited about, because it maps cleanly onto how AI agents want to generate documents.

invoice.html:

<h1>Invoice #{{ invoice_number }}</h1>
<p>{{ customer_name }}</p>
<table>
  {% for item in items %}
  <tr><td>{{ item.name }}</td><td>{{ item.price }}</td></tr>
  {% endfor %}
</table>

data.json:

{
  "invoice_number": "2026-001",
  "customer_name": "Acme Corp",
  "items": [
    { "name": "Widget", "price": "$10.00" },
    { "name": "Gadget", "price": "$25.00" }
  ]
}

fulgur render -o invoice.pdf -d data.json invoice.html

An AI agent emitting JSON is a very natural fit for this interface — it doesn't need to know anything about PDFs, just the data shape.

As a library

use fulgur::engine::Engine;
use fulgur::config::{PageSize, Margin};

let engine = Engine::builder()
    .page_size(PageSize::A4)
    .margin(Margin::uniform_mm(20.0))
    .title("My Document")
    .build();

let pdf = engine.render_html(html)?;

Honest about where it is today

I want to be upfront about something: fulgur is not "throw any HTML at it and get pixel-perfect PDFs." It's not a browser. It's a pagination-aware renderer that supports a curated subset of HTML and CSS, and within that subset it produces clean, predictable output. Push outside the supported surface and you'll see weird layout, missing styles, or things that just don't render.

That's a real limitation today, and I'm not going to pretend otherwise.

But here's the bet I'm making — and the reason I think the curated-subset approach is fine, even good, in 2026:

The consumers of this API are increasingly going to be AI agents, and they already know the web platform.

LLMs have absorbed an enormous amount of HTML and CSS during training. If you give an agent a JSON payload and say "render this as an invoice PDF," it will reach for <table>, flex, grid, standard typography — the well-trodden parts of the web platform. Those are exactly the parts I'm prioritizing.

So the design target isn't "render any webpage as a PDF." It's "give an AI agent a templating surface where its existing web-standards knowledge produces the right document, deterministically, without spinning up a browser." Different goal, different tradeoffs, much smaller surface to get right.

To keep this honest rather than aspirational, fulgur runs against the Web Platform Tests suite — the same conformance suite the major browsers use. The pass rate is the metric I'm tracking the supported-subset against, and it climbs with every release. "What does fulgur actually support?" stops being a vibe and becomes a number.

Current numbers, to be transparent about it:

WPT suite	Pass rate
`css-page`	62 / 257 (24.1%)
`css-multicol`	27 / 579 (4.7%)

Yes, those are low. They're also the real numbers, on the parts of the spec fulgur cares most about (Paged Media and multi-column layout). The point of putting them on the table is that they're now a number that can go up, release after release — not a hand-wavy "we support most of CSS." If you file a bug pointing at a specific WPT case that should pass, that's directly actionable.

That's where fulgur is heading. Today it's already useful for invoice-shaped, report-shaped, form-shaped documents. The supported surface grows — measurably — with every release.

Determinism, on purpose

One feature I want to call out separately: byte-identical output for identical input.

This sounds boring, but it's huge for CI. If your golden PDFs change byte-for-byte every time you re-run the pipeline, diffing them is useless. Fulgur's pipeline (Blitz → Taffy → Parley → Krilla) is deterministic by design.

The one caveat is fonts: Blitz currently calls fontdb::Database::load_system_fonts() for SVG <text> elements, which means the same HTML can produce different output on machines with different system fonts. The repo ships a pinned Noto bundle and a fontconfig setup that keeps examples/*/index.pdf byte-identical across CI, so you can get reproducible output today by pointing FONTCONFIG_FILE at a controlled font set.

How I'm building it: AI-driven solo dev

Fulgur is a one-person project, but it's been built with a fairly heavy AI tooling setup. A few things that have actually worked:

Claude Code + superpowers

I do most of the implementation work in Claude Code with the superpowers plugin. The loop is:

Brainstorm — talk through the design with Claude before writing anything
Plan — turn the design into a stepwise implementation plan
Implement — execute the plan, one chunk at a time

The brainstorm-then-plan structure keeps the agent from wandering off. It's also surprisingly good at catching "wait, this design has a hole" before any code is written.

term-cli for the debugger

term-cli lets an AI agent drive interactive programs through tmux. The killer use case for me is letting Claude Code drive a real debugger.

Without it, agents tend to fall back to println! debugging and spiral. With a debugger they can inspect variables directly, set breakpoints, and resolve "why is this layout offset wrong" in one shot. The behavior change is dramatic.

AI code review

I run Devin Review and CodeRabbit on every PR. PDF spec edge cases and CSS layout corner cases are exactly the kind of thing where having a second pair of eyes matters, and as a solo maintainer I don't have human reviewers. Both tools have caught real issues, especially around pagination edge cases.

It's not a substitute for a strong test suite — fulgur has a fixture-based golden PDF test setup — but it's a useful additional layer.

What's next

A few things on the roadmap:

More language bindings — Python (PyO3) and Ruby (Magnus) are already shipping; Node.js (napi-rs) is next.
More GCPM — there's still a long tail of CSS Paged Media features
A proper benchmarking harness that runs in CI on every release

The repo is here, with full README, threat model, and contribution guide:

👉 github.com/fulgur-rs/fulgur

Site: fulgur.dev

If you've been looking for a way to generate PDFs at scale without paying the Chromium tax, give it a try. Stars, issues, and PRs all very welcome — and if you hit a CSS edge case that breaks things, please open an issue with a minimal repro. That's the fastest path to fixing it.