Library

KatanA Render Runtime

A Rust library and CLI that convert diagram and TeX math sources to SVG, with shared input/output APIs for results and diagnostics.

Rust developers embedding SVG rendering for diagrams and math

01

Implemented capabilities

SVG rendering for Mermaid, Draw.io, ZenUML, and PlantUML

Evidence

TeX-to-SVG rendering through MathJax

Evidence

krr CLI commands for render, compare, reference-update, and bench

Evidence

02

Getting started

  1. Prepare Rust and the runtime assets described in the README, then install the krr CLI.
  2. Prepare a Mermaid input file and generate SVG with the render command.

Prepare Rust and the required development tools, then check the linked README for environment requirements before installing. Examples show an entry point and do not guarantee operation in every environment.

Evidence
sh
cargo install katana-render-runtime-cli
printf 'graph TD\n  A-->B\n' > sample.mmd
krr mermaid render --input sample.mmd --output sample.svg

01 / KRR

Where it fits

One SVG contract for diagrams and math

Pass Mermaid, ZenUML, Draw.io, PlantUML, or MathJax TeX as a typed RenderInput. KRR returns SVG, dimensions, viewBox, runtime information, warnings/errors, and a cache fingerprint in RenderOutput, so preview or document viewers need not implement each diagram kind themselves.

Diagnostic-aware math preview

MathJaxRenderer converts ordinary inline TeX and display math to SVG, while invalid TeX or a missing runtime keeps the input string and returns the reason in diagnostics.errors. Public tests verify SVG and dimensions for valid input and the original input, zero dimensions, and a non-empty error list for invalid input, allowing an editor to show the source and reason instead of failing the whole screen.

02 / KRR

Input to output

  1. Provide typed source

    Set RenderKind, the already-classified source string, RenderConfig, RenderPolicy, and RenderContext in RenderInput. KRR consumes diagram or TeX text directly; parsing a Markdown AST remains outside this renderer boundary.

  2. Resolve runtime and theme

    RuntimePathResolver prefers an explicitly supplied runtime path. When it is omitted, it resolves bundled Mermaid, Draw.io, or MathJax assets or a versioned PlantUML cache path; PlantUML also reads theme and cache-directory settings from vendor_config and reports invalid configuration as RenderError.

  3. Receive SVG and diagnostics

    Renderer::render returns RenderOutput for successful diagrams and math, including SVG and positive dimensions. Input errors or missing runtimes can return RenderError, while a backend may instead return the raw source with diagnostics, allowing callers to display and record warnings and errors.

03 / KRR

Key APIs and CLI

Renderer::render
The common entry point is Renderer::render(&RenderInput). A RenderKind/source combination unsupported by the backend produces UnsupportedKind, while runtime resolution failures are reported as errors such as RuntimeResolution.
RenderOutput
Returns svg, width, height, view_box, runtime, profile, diagnostics, and cache_fingerprint. The contract therefore carries display dimensions and reuse metadata in addition to the SVG string.
krr render
The CLI processes input files with krr mermaid render, krr drawio render, and krr plantuml render. It supports --output and --runtime, PlantUML-specific --theme, --theme-mode, and --cache-dir, and writes the result to standard output when no output file is supplied.
compare and bench
reference-update, compare, and bench operate on fixture directories. compare defaults to a 99.0 minimum score, which provides a regression-check path for integration but is a quality comparison mechanism rather than a guarantee of runtime performance.

04 / KRR

Concrete example

Handle invalid MathJax with diagnostics

Resolve a MathJax runtime with RuntimePathResolver, pass RenderInput containing \not_a_real_mathjax_command to MathJaxRenderer, and inspect the returned raw source and diagnostics. The render call still returns output with the original source, width and height of zero, and non-empty diagnostics.errors; valid E = mc^2 input instead returns SVG, viewBox, and positive dimensions.

rust
use katana_render_runtime::{
    MathJaxRenderer, RenderConfig, RenderContext, RenderInput, RenderKind,
    RenderPolicy, Renderer, RuntimePathResolver,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = RuntimePathResolver::resolve(RenderKind::MathJax, None)?;
    let renderer = MathJaxRenderer::with_runtime_path(runtime);
    let input = RenderInput {
        kind: RenderKind::MathJax,
        source: r"\not_a_real_mathjax_command".to_string(),
        config: RenderConfig::default(),
        policy: RenderPolicy::default(),
        context: RenderContext::default(),
    };
    let output = renderer.render(&input)?;
    println!("svg={} errors={:?}", output.svg, output.diagnostics.errors);
    Ok(())
}

05 / KRR

Integration boundaries

Prepare Rust and runtime assets

The published workspace requires Rust 1.95.0 and edition 2024, and its runtime assets for Mermaid, Draw.io, MathJax, and PlantUML are versioned and checksummed. Choose the bundled asset or replace it with an explicit path or environment-controlled runtime as the deployment requires.

Keep document responsibilities outside KRR

KRR is responsible for runtime rendering of already-classified diagram and TeX source. Parsing a Markdown AST, HTML/PDF/PNG/JPG document export, viewer/editor UI, KDV pagination, and document export remain responsibilities of the model, viewer, or application layer that composes KRR.

Evidence

This overview is based on the public repositories at the time of review. Verify implementation and usage in the linked pinned commits.

RepositoryREADME8654789f69d2
Evidence · KRR
All products