Rendering Mermaid

renderMermaid renders a Mermaid diagram definition to a self-contained, print-safe inline SVG (native <text> labels, no <foreignObject>), suitable for embedding verbatim in both web and print output.

The admitted native document provider stages its pinned Mermaid browser bundle inside supervised Chromium. It requires a configured Chromium executable and artifact workspace, with no separate Node/Bun provider process.

Signature

renderMermaid(
  definition: string,             // Mermaid source (supports {{template}} variables)
  theme?: string,                 // neutral | base | default | dark | forest (default: neutral)
  background?: string,            // CSS color or "transparent" (default: transparent)
  timeout?: number                // Backstop ms for the render step (default: 20000)
) -> string

Example

let diagram = renderMermaid(
  definition: "flowchart LR\n  Prompt --> Model\n  Model --> Result",
  theme: "neutral"
)
save(content: diagram, filename: "workflow.svg")

Use the SVG string directly in an HTML document, or save it as a file as shown above.

Error detection (fail fast, never silently)

renderMermaid validates with mermaid.parse() before rendering. A malformed diagram produces a structured parse failure with the parser's diagnostic:

Mermaid parse error: Parse error on line 2:
flowchart TB  A -->>> ??? B [
------------------^
Expecting 'AMP', 'COLON', 'PIPE', ...

Failures remain catchable Kaya errors and distinguish malformed input, render failure, timeout, cancellation and browser failure. The Rust boundary validates the returned SVG and rejects error graphics, HTML labels, scripts and external resources. A timeout reports that the operation did not finish within its configured limit; it does not establish that the diagram syntax was invalid.

Self-healing with generate() (composable)

Because the parse error is precise, it's ideal to feed back to a model to repair the diagram. renderMermaid stays deterministic; you compose the repair loop in Kaya with tuple-catch + generate():

function tryRenderMermaid(def: string): string {
  return renderMermaid(definition: def)
}

function repairMermaid(def: string, errorMessage: string): string {
  return generate(message: `The Mermaid diagram below failed to render.

Error:
{{errorMessage}}

Diagram:
{{def}}

Return ONLY the corrected Mermaid source — no prose, no code fences.`)
}

let definition = generate(message: "Write Mermaid source for a prompt-to-model-to-result flowchart. Return only the diagram source.")
let svg, err = tryRenderMermaid(def: definition)
if err != null {
  // Feed the precise parse error back to the model, then re-render.
  let fixed = repairMermaid(def: definition, errorMessage: err.message)
  svg = tryRenderMermaid(def: fixed)   // fails loud if still broken
}

This keeps the render path deterministic and uses the model only on the repair path. (For a multi-attempt loop, drive it the same way; each attempt feeds the latest err.message back to repairMermaid.)

Host Setup

Configure the renderer and grant the session access before running these examples. See the rendering overview for dependencies and the Tool Server guide for host setup.