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
02
Primeiros passos
- Prepare Rust e os assets de runtime indicados no README e instale a CLI krr.
- 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.
Fontescargo install katana-render-runtime-cli
printf 'graph TD\n A-->B\n' > sample.mmd
krr mermaid render --input sample.mmd --output sample.svg01 / 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
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.
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.
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.
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.