PlantUML Fences Design

Shipped in 2.5.1 (2026-10-26); @startsalt and @startnwdiag were added in 2.5.2. The repo spec is docs/superpowers/specs/2026-10-25-plantuml-fences-design.md; this page is the as-built summary. It is the second renderer on the hook described in RenderedFencesDesign, and the first one that draws on the server. For a live example, see the agent feature-delivery activity diagram on About.

Why PlantUML after Mermaid: fork/join activity and deep class diagrams

Mermaid has no real UML activity notation and only shallow class diagrams. Wikantik pages need two things it cannot give:

• Activity diagrams with explicit fork/join synchronisation bars, swimlanes, partitions, decisions and loops.
• Class diagrams that go deep into structure: realisation, abstract classes, interfaces, generics, stereotypes, packages, visibility, multiplicities, composition and aggregation.

People and content agents write and edit these diagrams by hand. Deriving diagrams from code is left to the agent; the wiki does not do it.

Spike results: activity diagrams, Smetana layout, speed and failure modes

The spike used plantuml-mit 1.2026.9; the release pins 1.2026.8.

• Activity diagrams (fork / fork again / end fork, split, swimlanes, while, notes) render correctly with PlantUML's own layout. No Graphviz is needed.
• Class diagrams use Smetana, PlantUML's built-in Java port of Graphviz. Quality was judged good enough, so Graphviz is never installed.
• A typical diagram takes 10–25 ms in a warm JVM, and 120 classes take about 140 ms.
• A 300-class diagram overflowed the stack inside Smetana, so hard limits are mandatory.
• In SANDBOX security mode, file and URL includes, environment variables and images are all refused. The bundled C4 standard library still works.

Which diagram types draw

@startuml diagrams are accepted, plus @startsalt wireframes and @startnwdiag network diagrams, which PlantUML 1.2026.8 only recognises under their own start line. A browser test per type proves these draw in the reader, in light and dark:

Salt and nwdiag lay themselves out without Graphviz, so the engine does not add the Smetana pragma to them. A salt wireframe:

@startsalt
{
  Login    | "agent@example.com "
  Password | "****              "
  [Cancel] | [  Sign in  ]
}
@endsalt

A network diagram:

@startnwdiag
nwdiag {
  network dmz {
    address = "203.0.113.0/24"
    proxy [address = "203.0.113.10"];
  }
  network internal {
    address = "10.0.0.0/24"
    proxy [address = "10.0.0.1"];
    wiki [address = "10.0.0.20"];
    db [address = "10.0.0.30"];
  }
}
@endnwdiag

License decisions that keep Wikantik commercially licensable

Wikantik never shows a PlantUML-generated error or welcome image, which is where PlantUML may place sponsored messages.

How a plantuml fence becomes a drawing: placeholders resolved at the edge

flowchart LR
  MD[Page markdown] --> Parse[Flexmark node renderer]
  Parse --> Check{Fail-closed policy}
  Check -->|refused| Refusal[Source plus reason]
  Check -->|allowed| Ph[Signed placeholder]
  Ph --> Cache[HTML and embed caches]
  Cache --> Resolve[Resolve at HTML exit]
  Resolve --> Pool[Bounded PlantUML pool]
  Pool --> Scrub[SVG scrub and id prefix]
  Scrub --> Out[Light and dark SVG]
  click Out "/wiki/RenderedFencesDesign"

• During Markdown rendering, the fence emits a placeholder: a hash of the source plus an HMAC under a per-JVM secret, so page text cannot forge one.
• Placeholders are resolved once, at the outermost textToHTML (nesting is counted by RenderDepth). Embeds and parses never draw, so a save never renders diagrams it would throw away.
• Page caches hold placeholders, never drawings. A timeout or a busy pool can therefore never be cached as a page's rendering, and nested embed sanitizing cannot strip a drawing.
• The HTML sanitizer is unchanged, so hand-written <svg> in a page is still stripped. Only PlantUML output, run through Wikantik's own allow-list SVG scrub, reaches the page. Tag scans in the resolver are length-capped, so hostile HTML cannot make resolution quadratic.

Policy, sandbox and limits against hostile or pathological diagrams

• Policy (check()). Refuses includes (except C4), file and environment built-ins, indirect calls (%call_user_func, %invoke_procedure, %eval), <img: labels, unsafe link targets, help/crash and oversized sources. A literal {{ }} sub-diagram is refused as a first line of defence. These rules apply to salt and nwdiag exactly as to @startuml.
• Containment that does not depend on the policy. The sandbox is set process-wide and GRAPHVIZ_DOT points at a path that does not exist, so dot can never run, even for a sub-diagram built through the preprocessor. Any nested image is scrubbed, and every render is time-bounded.
• Limits. The source cap is 64 KB and the raw SVG is capped at 512 KB per variant. Each render gets a 5 s timeout, measured from when it starts, on a 2-thread pool with 16 MB stacks. A full pool gives a "busy" refusal instead of blocking.
• Failure caching. A stack overflow is cached as too-complex. A timeout is cached as too-slow for 10 minutes, then retried once. A PlantUML crash is render-crashed (a malformed salt wireframe lands here: salt has no parse-error diagram). Concurrent requests for one diagram share a single render, and the outcome cache is capped by bytes.
• Per-page budget. At most 20 diagrams and 8 MB of drawings per response (page-limit), within a total of 10 s (page-budget).
• Kill switch. wikantik.fences.plantuml.enabled replaces drawings with a notice. Diagram links still count as references, so flipping it never changes the Page Graph.

Reader, editor and dark-mode behaviour

• Each diagram ships as both a light and a dark SVG, and CSS picks one from the app theme. Readers without JavaScript get the light one.
• It has the same toolbar as Mermaid: Show source, Copy, and Expand. Expand suffixes cloned ids so they stay unique in the document.
• Both editor previews call POST /api/fences/render, which requires an authenticated user and passes the same Origin-based cross-site check as the other /api posts. The previews debounce, keep the previous drawing dimmed until its replacement arrives, and show PlantUML's error with its line number.
• [[/wiki/Page]] links inside a diagram feed backlinks, the Page Graph and broken links, exactly as Mermaid click links do.

Corpus checking with check-plantuml.sh

bin/check-plantuml.sh [--json] <files|dir|-> draws every PlantUML diagram it finds through the same policy and engine. It exits 0 when all diagrams draw, 1 when some fail, and 2 when the checker itself fails — the same contract as check-mermaid.mjs.

Deliberately out of scope for PlantUML fences

• Graphviz or ELK.
• PlantUML types that need their own @start… line, other than salt and nwdiag (see the table above).
• Generating diagrams from code.
• Rewriting diagram links on rename.
• PNG output, Kroki and Vega-Lite.

See WikantikDevelopmentHub for the rest of the platform designs.