Biblioteca

KatanA Render Runtime

Biblioteca Rust e CLI que convertem fontes de diagramas e fórmulas TeX para SVG. Uma API comum devolve resultado de renderização e diagnósticos.

Desenvolvedores Rust que integram renderização SVG de diagramas e fórmulas

01

Funções implementadas

Renderização SVG de Mermaid, Draw.io, ZenUML e PlantUML

Fontes

Renderização SVG de TeX via MathJax

Fontes

Comandos render, compare, reference-update e bench da krr CLI

Fontes

02

Primeiros passos

  1. Prepare Rust e os assets de runtime indicados no README e instale a CLI krr.
  2. Prepare um arquivo Mermaid e gere SVG com o comando render.

Prepare Rust e as ferramentas de desenvolvimento necessárias e consulte o README indicado para os requisitos antes da integração. Os exemplos são pontos de entrada e não garantem funcionamento em todos os ambientes.

Fontes
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

Casos de uso

Converter diagramas e fórmulas em SVG pelo mesmo contrato

Passe fontes de diagramas Mermaid, ZenUML, Draw.io e PlantUML, além de TeX do MathJax, como RenderInput tipado. O KRR escolhe o runtime e retorna RenderOutput com SVG, dimensões, viewBox, informações do runtime, avisos, erros e cache fingerprint; assim, preview e viewer não precisam de uma implementação por tipo de diagrama.

Visualizar fórmulas com diagnóstico

MathJaxRenderer converte TeX inline e display em SVG e, para TeX inválido ou runtime ausente, conserva a string de entrada e devolve o motivo em diagnostics.errors. É adequado para mostrar a fonte e o diagnóstico no editor sem transformar uma falha de render em falha da tela inteira. Os testes públicos verificam SVG e dimensões no caminho normal, e entrada original, dimensões 0 e erro não vazio no caminho anormal.

02 / KRR

Fluxo da entrada à saída

  1. Informar source e tipo

    O chamador configura RenderKind, source classificado, RenderConfig, RenderPolicy e RenderContext em RenderInput. O KRR não recebe Markdown AST: sua responsabilidade é processar diretamente a string do diagrama ou do TeX.

  2. Resolver runtime e tema

    RuntimePathResolver prioriza o runtime path explícito; sem ele, resolve bundled assets de Mermaid, Draw.io e MathJax, e o PlantUML versioned cache path. Para PlantUML, lê o tema e o cache directory de vendor_config e devolve RenderError quando a configuração é inválida.

  3. Receber SVG e diagnósticos

    Renderer::render retorna RenderOutput. Para diagramas e fórmulas válidos, há SVG e dimensões positivas; para erro de entrada ou runtime ausente, há RenderError ou raw source e diagnostics definidos pelo backend, permitindo ao consumidor exibir e registrar avisos e erros.

03 / KRR

APIs e CLI principais

Renderer::render — Contrato de renderização
A entrada unificada é Renderer::render(&RenderInput). Combinações incompatíveis de RenderKind e source produzem UnsupportedKind; falhas ao resolver o runtime produzem RenderError, como RuntimeResolution.
RenderOutput — Dados de saída
A saída inclui svg, width, height, view_box, runtime, profile, diagnostics e cache_fingerprint. Além da string SVG, ela fornece dimensões de exibição e metadados para decidir a reutilização.
krr render — Entrada CLI
A CLI processa arquivos com krr mermaid render, krr drawio render e krr plantuml render. Aceita --output, --runtime e, para PlantUML, --theme, --theme-mode e --cache-dir; sem arquivo de saída, escreve o resultado em stdout.
Comandos de comparação e diagnóstico
reference-update, compare e bench usam um fixture directory. O minimum score padrão de compare é 99.0: é um caminho de regressão para a integração, não uma garantia de desempenho de execução.

04 / KRR

Entenda com um exemplo

Diagnosticar uma entrada MathJax inválida

No Rust, resolva o runtime MathJax com RuntimePathResolver e passe um RenderInput a MathJaxRenderer. Com \not_a_real_mathjax_command, render ainda devolve uma saída: svg repete a entrada, width e height são 0 e diagnostics.errors não fica vazio. Com E = mc^2, o resultado tem SVG, viewBox e largura e altura positivas.

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

Integração e limites

Pré-requisitos de adoção

O workspace público usa Rust 1.95.0 e edition 2024; os runtime assets de Mermaid, Draw.io, MathJax e PlantUML são controlados por versão e checksum. Você pode usar os assets padrão ou escolher um runtime por path explícito ou variável de ambiente.

Fronteira de responsabilidade

O KRR renderiza no runtime fontes classificadas de diagramas e TeX. Não analisa Markdown AST, não exporta documentos para HTML/PDF/PNG/JPG, não fornece UI de viewer/editor e não cuida de pagination ou document export do KDV; essas responsabilidades ficam no modelo, viewer ou aplicação de nível superior.

Fontes

Apresentação baseada nos repositórios públicos disponíveis no momento da pesquisa. A implementação e os passos podem ser conferidos no commit fixado do link.

RepositórioLeia-me8654789f69d2
Fontes · KRR
Todos os produtos