Biblioteca

KatanA Render Runtime

Biblioteca Rust y CLI que convierten fuentes de diagramas y fórmulas TeX a SVG. Una API común devuelve el resultado de renderizado y los diagnósticos.

Desarrolladores Rust que integran renderizado SVG de diagramas y fórmulas

01

Funciones implementadas

Renderizado SVG de Mermaid, Draw.io, ZenUML y PlantUML

Fuentes

Renderizado SVG de TeX mediante MathJax

Fuentes

Comandos render, compare, reference-update y bench de krr CLI

Fuentes

02

Primeros pasos

  1. Prepare Rust y los assets de runtime indicados en el README e instale la CLI krr.
  2. Prepare un archivo de entrada Mermaid y genere SVG con el comando render.

Prepare Rust y las herramientas de desarrollo necesarias y consulte el README enlazado para conocer los requisitos antes de integrar. Los ejemplos son puntos de entrada y no garantizan el funcionamiento en todos los entornos.

Fuentes
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

Convertir diagramas y fórmulas a SVG con un contrato común

Pase fuentes de Mermaid, ZenUML, Draw.io y PlantUML, y TeX de MathJax como RenderInput tipado. KRR elige el runtime y devuelve RenderOutput con SVG, dimensiones, viewBox, información del runtime, advertencias, errores y cache fingerprint, sin que el viewer implemente cada tipo.

Previsualizar entradas TeX con diagnóstico

MathJaxRenderer convierte TeX inline y display a SVG; con TeX inválido o runtime no instalado conserva el texto de entrada y devuelve la razón en diagnostics.errors. Los tests públicos comprueban SVG y dimensiones en el caso normal, y entrada original, dimensiones 0 y errores no vacíos en el anómalo.

02 / KRR

Flujo de entrada a salida

  1. Introducir source y tipo

    Configure en RenderInput RenderKind, source clasificado, RenderConfig, RenderPolicy y RenderContext. KRR procesa directamente texto de diagramas o TeX; no recibe un Markdown AST.

  2. Resolver runtime y theme

    RuntimePathResolver da prioridad a un runtime path explícito y, si falta, resuelve assets bundled de Mermaid, Draw.io y MathJax, y el cache path versionado de PlantUML. En PlantUML lee theme y cache directory desde vendor_config y devuelve RenderError si la configuración es inválida.

  3. Recibir SVG y diagnóstico

    Renderer::render devuelve RenderOutput. Un diagrama o fórmula válido produce SVG y dimensiones positivas; un error de entrada o runtime ausente produce RenderError, o raw source y diagnostics definidos por el backend, para que el host registre advertencias y errores.

03 / KRR

APIs y CLI principales

Renderer::render — Contrato de renderizado
La entrada unificada es Renderer::render(&RenderInput). Una combinación incompatible de RenderKind y source produce UnsupportedKind; un fallo de resolución produce RenderError como RuntimeResolution.
RenderOutput — Datos de salida
Incluye svg, width, height, view_box, runtime, profile, diagnostics y cache_fingerprint. Recibe dimensiones y metadatos para decidir la reutilización, no solo una cadena SVG.
krr render — Entrada CLI
La CLI procesa archivos con krr mermaid render, krr drawio render y krr plantuml render. Admite --output, --runtime y, para PlantUML, --theme, --theme-mode y --cache-dir; sin archivo de salida escribe el resultado en stdout.
Comandos de comparación y diagnóstico
reference-update, compare y bench trabajan sobre un fixture directory. El minimum score predeterminado de compare es 99.0: sirve para regresiones de integración, pero no garantiza la ejecución ni el rendimiento.

04 / KRR

Entender con un ejemplo

Tratar MathJax inválido con diagnósticos

Resuelva un runtime de MathJax con RuntimePathResolver y pase a MathJaxRenderer un RenderInput que contenga \not_a_real_mathjax_command. Incluso con esa entrada inválida, render devuelve la fuente original, width y height iguales a 0 y diagnostics.errors no vacío; una entrada válida E = mc^2 devuelve SVG, viewBox y dimensiones 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

Integración y límites

Requisitos de integración

El workspace público usa Rust 1.95.0 y edition 2024, y administra version y checksum de assets Mermaid, Draw.io, MathJax y PlantUML. Puede usar los assets predeterminados o sustituirlos con path explícito o variables de entorno.

Límite de responsabilidad

KRR renderiza source clasificado de diagramas y TeX. No analiza Markdown AST, no exporta documentos HTML/PDF/PNG/JPG, no implementa viewer/editor UI ni pagination y export de documentos de KDV; esas responsabilidades corresponden al modelo, viewer o aplicación superior.

Fuentes

Presentación basada en los repositorios públicos disponibles en el momento de la investigación. La implementación y los pasos se pueden comprobar en el commit fijado del enlace.

RepositorioLéame8654789f69d2
Fuentes · KRR
Todos los productos