Why Plotwork draws plain SVG

TL;DR

1. Drawn once, shown as a file

Most diagram-as-code tools draw at view time. A Mermaid fence is text until a script in the page, or the host's own viewer, turns it into a picture in the reader's browser. A PlantUML diagram is drawn by Java, usually behind a server the page asks each time it shows the picture.

Plotwork moves the drawing to the moment the diagram is written. The agent, the command line, the Action or the API lays the diagram out and writes an SVG file next to its source. From then on the file is the diagram:

The page that shows the diagram imports nothing from Plotwork and needs no build step, plugin, or script for it.

2. What ships to the reader

Mermaid can also be drawn ahead of time with its command line, which runs a headless browser to do it. That removes the script from the page, and keeps the browser in your build.

3. Why fewer runtime dependencies matters

A script a page loads runs with the page's full rights: it can read what the reader types, change what they see, and send it anywhere. A package a build installs runs on the developer's machine or the CI runner, often with tokens in reach. Attackers know this, and the incidents below are a few of the public ones. None involved a diagram tool. Each shows a way trusted code changed hands.

Two lessons apply to diagrams. A script loaded from a CDN, as polyfill.io was, is only as safe as whoever owns that domain next. And a deep install tree, as Shai-Hulud showed, is many maintainers' accounts that each have to stay safe. A static picture asks the reader's page to trust neither.

4. What is in the file

Every picture Plotwork draws is an SVG document with these properties, and every picture on this site is checked against them.

Browsers add a second wall. An SVG shown through an <img> tag or a CSS background runs no script and loads no outside resource, whatever it holds (MDN: SVG as an image (opens in a new tab)). That is why Plotwork carries icons inside the file: they show in an image tag, where an outside reference would not.

Custom icons

An organisation's own icons go through an allowlist before they can be drawn. Only shapes, groups, gradients, clips, masks and titles are kept, with paint and geometry attributes. A <script>, foreignObject, <style> block, <image>, <a>, <use>, text or filter is refused with a reason. See What a file may hold.

5. Hosted pictures

A published diagram is served from cdn.plotwork.dev with this header:

Content-Security-Policy: default-src 'none'; img-src data:; style-src 'unsafe-inline'; sandbox

If a script ever appeared in a hosted picture opened as a page, this policy and the sandbox would stop it from running. Only the icons the file carries as data: images load.

Embedding a hosted link means the reader's browser fetches an image from Plotwork. To fetch nothing from anyone, commit the SVG file to your repository and serve it with your own pages.

6. What still uses packages, and how they are secured

The tools that draw are software, and you install them. They run when a diagram is written or checked, in an editor, on a developer's machine or in CI, and never in the page a reader opens.

The bundles contain other people's code, such as the layout engine. It is chosen when the bundle is built, from a locked dependency tree installed with install scripts turned off, and every package in it is listed with its licence in THIRD-PARTY-NOTICES.md. A compromise upstream would have to land before a build and pass its tests to reach a release, and a pinned release never changes after you review it.

7. Other things a plain file gives you

See also