DEV Community: Gray Chen

Word doesn't rasterize your Mermaid SVG — it drops the labels

Gray Chen — Tue, 27 Oct 2026 04:55:57 +0000

Something that keeps coming up in Word support threads: you put a diagram into Word and the labels are missing. The boxes render. The arrows render. The text inside them doesn't.

There's a second complaint that sounds unrelated, usually from someone who went through a converter: the drawing behaves like a photograph. You can't select a box, you can't retype a label, you scale it up and it goes soft.

Those two symptoms look like unrelated bugs. They're the same bug, and it isn't the file format.

It's one element inside the SVG — the element every diagram renderer uses to place a label.

Two ways Word can hold a drawing

Word has exactly two models for a drawing, and they aren't variants of each other.

The first is a picture. One object, one blob of pixels or vectors. You can move it, resize it, and that's the whole vocabulary.

The second is a set of native shapes — the same objects you get from Insert → Shapes. Each one has a geometry, a text frame you can click into and type, and a position in a z-order. Connectors are their own object type, and the important part is that a connector's endpoints can be bound to two specific shapes.

That binding is what makes a Word diagram feel alive: drag a box, and every arrow attached to it follows, because the arrow isn't drawn — it's computed from the two shapes it points at.

A picture has none of this. Which is why the difference between the two models is not "quality". It's whether the diagram survives its first revision.

Why Mermaid hits the foreignObject wall

Mermaid renders to SVG, and like most diagram tools it puts text inside shapes using <foreignObject>.

<foreignObject> is the standard trick for embedding a chunk of HTML inside an SVG drawing. It exists because raw SVG text layout is genuinely miserable — <text> plus manual <tspan> lines with hand-computed wrapping, no automatic line height, no rich inline styling. If you want a label that wraps and respects CSS, <foreignObject> is the only sane answer.

Word does not implement it.

And it doesn't degrade gracefully. The moment Word imports the SVG — before you've asked it to do anything — it translates the drawing into its own object model, keeps every geometric primitive, and drops the contents of the foreignObject. The box that held the label survives. The label doesn't. There's no error, no warning, and nothing recovers it: converting the picture into shapes afterwards hands you the same empty boxes. You find out when you're looking at a flowchart made of blank rectangles — or when someone else is.

That single unimplemented element is also the reason almost every "Mermaid to Word" converter hands you a PNG at 2× and calls it done. Seen from here, that isn't laziness. Given what Word does with foreignObject, a bitmap is the honest fallback: at least the labels stay readable. You just can't touch them.

Reproduce it yourself

Worth doing before you trust any of this, including the parts I got wrong at first:

Save an .svg containing one plain <text> line and one <foreignObject> holding two <div>s.
Insert it into Word (Insert → Pictures). It arrives as a single picture — and the damage is already done: the foreignObject box is empty, while the plain <text> line is right there.
Right-click → Convert to Shape, to rule out "it's in there and just not drawn". It stays empty.
Click the text. The plain <text> line became a text box you can retype. The foreignObject block never contained anything to click.

The first time I ran this I expected a slightly soft version of my labels, since "unsupported element" usually means it degrades to pixels. What came back was nothing — the box, the border, the rounded corners, and no text at all. No conversion, no intervention: that's what the import alone produced.

Three ways out, and what each one costs

Once you frame the problem as "the text lives somewhere Word can't read", the options become clear, and all three are defensible.

1. Rasterize. Render at 2× or 3× and embed the image. Cheap, universal, works for every diagram anyone will ever draw. Cost: zero editability, ever. It's also the option that quietly guarantees the diagram goes stale.

2. Keep the SVG, avoid foreignObject. If you export with text converted to <text> and <tspan>, Word reads the drawing as real vector shapes and you can scale it losslessly. Cost: the text becomes fixed geometry. You can move the whole label, you can't retype it. For a diagram that will never change, that's a fine trade. For an architecture doc, it isn't.

3. Drop the SVG entirely and emit native shapes. Walk the layout yourself, and produce one Word shape per node, one Word connector per edge, with the connector's stCxn / endCxn pointing at the real shape ids. Nothing is an image, and the text lives in a text frame.

Option 3 is the only one that survives someone saying "change this box". It's also the one almost nobody ships, because it means re-implementing the layout pass instead of calling a renderer.

The wall behind the wall

Escape foreignObject — export with the labels flattened to <text> and <tspan> — and the drawing inserts looking correct. Every label sits exactly where the browser put it. Option 2 appears to work.

Then someone right-clicks and chooses Convert to Shape, and it comes apart. The boxes keep their width. The text inside them doesn't: labels that fit a second ago run past the shape edge, or lose their trailing characters to a clip. Nothing was dropped this time. It's all there, and it's all in the wrong place.

The reason a <text> element is only half a fix: it carries an anchor point and a font size, but no box width. In SVG, how wide a string is belongs entirely to the renderer's font metrics. Before conversion Word isn't typesetting anything — it copies each coordinate and each font size into DrawingML, which is why the preview matches the browser exactly. After conversion, every shape owns its own text frame, and Word measures the string with its own metrics. Different engine, same box.

Our DOCX writer hit the same class of bug on a real Word build. We had written a node's font size as 24 half-points — 16px — against a live Chromium measurement of 14px. That's 14.3% wider than the box had been sized for, and Word doesn't shrink text to fit a fixed frame; it clips. A node reading Manual approval came through showing only Manual, its second line cut off by the fixed line height. An edge label reading No came back as N.

So "flatten to <text> and it scales losslessly" holds only while nobody edits it. The moment they do, you're back to predicting a text-measurement engine you don't own — which is precisely why option 3 can't just hand Word an SVG and hope for the best.

What emitting native shapes actually involves

This is where the work is, so it's worth being concrete about three things that surprised me.

The shape count is not the node count. In Mermaid, ([...]) is a stadium/capsule node, and the renderer gives it a separate text box layered on the shape. So a capsule node costs you two <wps:wsp> elements rather than one. A seven-node flowchart containing a single capsule node therefore yields 17 shapes instead of 16 — 7 nodes, 7 connectors, 2 edge labels, plus that extra text box. Switching the terminal node from ([...]) to [...] brings it to 16.

The lesson isn't Mermaid trivia. It's that "the counts match" is a weak assertion unless you know which renderer artifact you're counting. Ours carried a stale number in a handful of places for a while — the example diagram changed, the figure in the copy didn't. That's exactly the failure mode an assertion like this exists to catch, and it only catches it when the number is read out of the artifact rather than maintained by hand.

Connector binding is the whole feature. A connector that merely looks attached is drawn line art and will sit still when you drag a box. Real binding means writing both ends into the XML — start and end connection ids — and then verifying all of them resolved. In my case, 7 of 7, and that assertion is in the test suite, because a silent 6-of-7 is worse than a visible failure.

Layout has to be reimplemented, not reused. The renderer's <path> is the wrong abstraction for Word connectors. Connectors need to route between two shape boundaries, which means working from node geometry and edge routing rules, not from a flattened path. Anything you can't express that way — custom edge styling, hand-tuned routing, decorative markers — doesn't come through.

Where it breaks

A 7-node flowchart with straight-ish edges emits cleanly — the word matters here, because that's the shape-writing path, not Word's own Convert to Shape. Whether a 60-node hairball with custom class styling survives is a different question, and I'd rather flag it as the place I'd expect it to fail than imply I've proven otherwise — custom class styling and curved edge routing are the two things that have no clean equivalent in a Word connector.

I think that boundary is worth stating plainly, because the alternative is a tool that quietly lies about complex input. The honest version is: native shapes work well for diagrams whose value is that people need to edit them — process flows, org charts, architecture sketches — and poorly for diagrams whose value is that they look exactly a certain way.

That's most of the difference between "I exported my diagram" and "my diagram is now in the document".

I ended up building the option-3 path for Mermaid, running in the browser with no upload: filecabin.app/document/mermaid-to-word. The mechanism section above is the part I'd want regardless of which converter you use — what Word does with foreignObject is a Word behavior, not a tool's choice.

7.2 KB of my first-paint script wasn't mine — and my own size budget was hiding it

Gray Chen — Wed, 30 Sep 2026 14:47:40 +0000

This site is a browser-side toolkit. You pick a file, it gets resized or converted, and nothing is uploaded anywhere.

That promise is the product. But it comes with a cost: it moves the work from my machine to yours. No server pays for the CPU, and no server pays for the download either. Whatever a tool needs has to arrive before the tool can be used.

That is easy to forget on a laptop on wifi. On a phone on mobile data, it is the difference between a tool and a spinner. And this is a site people use once: no account, no sign-up, no reason to come back and wait a second time. So the bytes a page needs before it works are the first impression.

I wanted that number written down, instead of estimated by feel. The plan for the site has the real budgets: 50 KB of first-paint JavaScript, 100 KB for HTML + CSS + JS together, and 500 KB for the full first load including fonts and images.

On top of those, I kept a stricter number for myself. "The limit you must not cross" and "the early warning that fires first" are two different jobs, and I wanted both. My early warning sat at 20 KB.

Where did 20 KB come from? I measured the tool pages, then added room for the tool I was about to build. The comment next to the constant said it left "about 108% headroom for new components," which sounded reasonable at the time. It took me one day to ask the only question that mattered: headroom above what?

1. Opening the box

Each tool on this site is an "island": a chunk of HTML that arrives already rendered, plus a small client script that later attaches behavior to it. The pattern is called islands — render everything up front, then add interactivity only where it is needed. The page is usable before any JavaScript runs.

The first version built those islands with Preact. Tool pages shipped up to 11.2 KB across five files — four of them framework, one of them mine:

chunk (one file each)	gzip	size	share
`preact.module`	4,412 B	4.3 KB	38%
`client.*` — Astro hydration client	1,405 B	1.4 KB	12%
`hooks.module`	1,161 B	1.1 KB	10%
`jsxRuntime.module`	399 B	0.4 KB	4%
framework subtotal	7,377 B	7.2 KB	64%
`Tool.*` — my own island	4,100 B	4.0 KB	36%
total	11,477 B	11.2 KB	100%

The two bolded rows are sums of the rows above them — the gzip column adds to 11,477 B once, and share to 100%.

Read that table again. Two thirds of the first paint was not the product.

Worse, the part that could actually regress — the compress / convert / resize logic — was the smaller half. I was measuring my own code with the same ruler I used for 7.2 KB of code I had not written and could not fix.

That answers my own question. I had set the headroom on top of a baseline that was 64% framework. With four tools shipped, first paint was already 11.2 KB — past the halfway mark of a 20 KB ceiling, and two thirds of it still not mine. Adding a tool properly grows first paint by roughly 1.5 KB, so 20 KB would have kept passing while the framework quietly ate a budget I thought was mine.

2. Deleting the framework was the easy part

I removed the framework integration and split the same UI into two halves:

build time renders the complete UI into HTML, so there is a working interface with zero JS, and something for a crawler to read;
runtime attaches behavior to it — events, state, text.

The same pages went from 11.2 KB across five files to 1.2 KB in one. That was a one-day change, and it is the part everyone writes about.

The part that took longer was making the number honest. Start with one detail: both readings above came from a ruler that could not see the inline scripts on the page. The honest per-page figure today is 3.4 KB (section 4).

If you want the opposite direction — building small on purpose from the first commit — there is a good write-up here on DEV: I shipped a working landing page in 14 KB. Here is every byte. Mine was the other direction: bytes already in the file, wearing my name, that I had not written.

Bug #1: I was counting the wrong thing, twice

My first collector walked the HTML, grabbed every <script src="…">, and added them up. The number was wrong by roughly 3×.

Here is why. The entry point of a script is not always a src attribute. A bundler can emit a module script whose body imports the real chunk, and a scan that only looks at src sees none of it. Two hand-written inline scripts on the page — 2 KB gzipped between them — were invisible for the same reason.

I fixed that and thought I was done. Then I added a mobile nav toggle: about 0.3 KB typed straight into <head>. The reading did not move. The collector had the same blind spot in a second place: it only followed _astro/*.js files.

That is the failure mode I keep coming back to. A size guard that cannot see the code you write by hand does not protect your budget — it protects the framework's share of it. On a small site, the thing that grows fastest is exactly those small snippets you paste in while building features.

So the rule became: the guard must not be narrower than the thing being measured.

Trap #2: don't punish the correct answer

Here is the subtle one — and this one I did not walk into. Heavy code — an image decoder, an audio encoder — is loaded with a dynamic import(). That puts it in its own async chunk, which never touches the first paint. That is the whole point of the architecture.

A guard that counts every import would flag the one technique that keeps first paint small. You would have a robot failing the build for doing the right thing, and after the second false alarm someone turns the guard off.

So the collector follows static imports only. The regex matches from"…" and import"…" — both followed by a quote. import( is followed by a parenthesis, so dynamic imports never match. The difference is one character wide, and it decides whether the guard helps you or fights you.

I am not claiming this is airtight. A module can call import() at the top level: nothing in the static graph points to it, and a byte ceiling cannot see what is not in the graph. That gap is real. I would rather write it down than pretend otherwise.

3. Make "stricter" something the machine enforces

With the framework gone, the warning line came down from 20 KB to 4 KB. There are two numbers in the repo now:

const BUDGET_FIRST_JS  = 50 * 1024;  // the plan's hard limit
const FIRST_JS_CEILING =  4 * 1024;  // the regression guard — stricter, on purpose

A stricter number only means something if it stays stricter. So the script refuses to run when the internal number has been loosened past the plan's budget:

if (FIRST_JS_CEILING > BUDGET_FIRST_JS) {
  console.error('✗ the regression guard is looser than the plan budget');
  process.exit(1);
}

Without that four-line check, "we are stricter than we need to be" is a sentence in a document. With it, it is a property of the build.

4. The number is also a proxy — that's why it's 4 KB

I also do not ship WebAssembly. Nothing needs it: image work goes through createImageBitmap, canvas, and OffscreenCanvas inside a worker.

The "no WASM" rule and the size ceiling turn out to be the same check. The smallest WASM image decoder worth using starts around 200 KB. libheif is closer to 1 MB, and the common HEIC wrappers land near 500 KB. Those are uncompressed numbers; even the smallest of them is still well over 10× a 4 KB ceiling once compressed. So there is no gray zone: if someone statically imports a decoder, the build breaks the same day.

One number enforcing both "the page stays light" and "no WASM sneaks into the critical path" is a better deal than two policies somebody has to remember.

And you can check it from the outside, which I like. On the deployed site, the only script the build controls has no static imports at all — five dynamic ones:

compress: () => import('../tools/image-compress-to-size/mount.ts'),
convert:  () => import('../tools/image-convert/mount.ts'),
// …

The site has gone from one island to nine since then. The deployed build lags a couple of releases behind, which is why the script above lists five. Largest first-paint script, measured per page: still 3.4 KB.

One boundary on that number, since I am asking you to verify it. The guard counts what our build emits: the _astro chunks reachable from the import graph, plus the inline scripts we hand-write. It does not count the analytics beacon Cloudflare injects at the edge, because that is third-party code we do not bundle. I would rather name the edge of the measurement than imply the number covers the whole page.

5. What the 7.2 KB was buying

Deleting the framework was not free. The bill just does not arrive in kilobytes:

skeleton and behavior are connected by a hand-written contract — data-role attributes and class names. Change one side and you must change the other. A runtime assertion throws the moment they disagree, and that assertion is the only reason this stays survivable.
there is no diffing. List updates are written by hand.
the initial text in the skeleton must match the first render word for word, or the page visibly twitches the instant it attaches.
adding a tool is one extra step compared to writing a component.

That is what 7.2 KB buys: a fair price for a site that adds new screens faster than it adds new pages.

I was not buying that. This site adds tools, which are mostly logic, and it reuses the same few interaction patterns. I was paying a framework tax every week for something I needed once — out of a budget I had told myself was mine.

If your first paint is mostly React and you are fine with that, this is not an argument with you. The lesson I would pass on is smaller and more annoying: a size budget is only as good as the thing it measures. Mine stayed green the whole time and told me nothing about the code I was writing.

The tools run at https://filecabin.app if you want to read the headers yourself — connect-src 'self', no 'wasm-unsafe-eval', and the same script quoted above.

If you have had a size guard turn out to be measuring the wrong thing, I would like to hear about it.