Bibliothèque

KatanA Render Runtime

Une bibliothèque Rust et une CLI qui convertissent les sources de diagrammes et de formules TeX en SVG, avec des API d'entrée/sortie communes pour les résultats et diagnostics.

Développeurs Rust qui intègrent le rendu SVG de diagrammes et de formules

01

Capacités implémentées

Rendu SVG pour Mermaid, Draw.io, ZenUML et PlantUML

Références

Commandes de la CLI krr : render, compare, reference-update et bench

Références

02

Premiers pas

  1. Préparez Rust et les assets de runtime indiqués dans le README, puis installez la CLI krr.
  2. Préparez un fichier Mermaid et générez un SVG avec la commande render.

Préparez Rust et les outils de développement nécessaires, puis consultez le README lié pour les prérequis avant l'installation. Les exemples indiquent un point de départ et ne garantissent pas le fonctionnement dans tous les environnements.

Références
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

Cas d'utilisation

Un contrat SVG pour diagrammes et formules

Passez les sources Mermaid, ZenUML, Draw.io, PlantUML et le TeX MathJax comme RenderInput typé. KRR renvoie SVG, dimensions, viewBox, informations de runtime, avertissements/erreurs et cache fingerprint dans RenderOutput ; le viewer n'a donc pas à implémenter chaque type de diagramme.

Prévisualiser les formules avec diagnostics

MathJaxRenderer convertit le TeX inline et display en SVG. Un TeX invalide ou un runtime absent conserve la chaîne d'entrée et explique la cause dans diagnostics.errors, afin que l'éditeur affiche source et diagnostic sans faire échouer tout l'écran. Les tests publics vérifient SVG et dimensions valides, puis entrée originale, dimensions nulles et erreur non vide en cas d'échec.

02 / KRR

Flux entrée-sortie

  1. Fournir une source typée

    Renseignez RenderKind, la source déjà classifiée, RenderConfig, RenderPolicy et RenderContext dans RenderInput. KRR traite directement le texte du diagramme ou du TeX ; l'analyse d'un AST Markdown reste hors de cette frontière.

  2. Résoudre le runtime et le thème

    RuntimePathResolver donne priorité au runtime path explicite. Sinon, il résout les assets Mermaid, Draw.io ou MathJax bundled, ou le cache path versionné de PlantUML. PlantUML lit theme et cache directory de vendor_config et renvoie RenderError si la configuration est invalide.

  3. Recevoir SVG et diagnostics

    Renderer::render renvoie RenderOutput : SVG et dimensions positives pour une entrée valide. Une erreur d'entrée ou l'absence du runtime peut produire RenderError ; un backend peut aussi renvoyer la source brute avec diagnostics, que l'appelant affiche et enregistre.

03 / KRR

API et CLI principales

Renderer::render — Contrat de rendu
L'entrée commune est Renderer::render(&RenderInput). Une combinaison RenderKind/source non prise en charge produit UnsupportedKind ; un échec de résolution du runtime produit une erreur comme RuntimeResolution.
RenderOutput — Données de sortie
La sortie contient svg, width, height, view_box, runtime, profile, diagnostics et cache_fingerprint : le contrat fournit donc dimensions d'affichage et métadonnées de réutilisation en plus du SVG.
krr render — Entrée CLI
La CLI traite les fichiers avec krr mermaid render, krr drawio render et krr plantuml render. Elle accepte --output, --runtime, ainsi que --theme, --theme-mode et --cache-dir pour PlantUML ; sans fichier de sortie, elle écrit sur stdout.
Commandes de comparaison et diagnostic
reference-update, compare et bench travaillent sur des fixture directories. compare utilise un minimum score par défaut de 99.0 : c'est une voie de régression et de comparaison de qualité, pas une garantie de performance d'exécution.

04 / KRR

Comprendre par un exemple

Diagnostiquer une entrée MathJax invalide

Le code résout les assets MathJax avec RuntimePathResolver, crée un MathJaxRenderer, puis lui passe un RenderInput contenant une commande invalide. render renvoie un résultat dont le SVG, la source brute et les diagnostics peuvent être examinés ; cet exemple ne produit pas un document PDF ou une UI.

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

Intégration et limites

Préparer Rust et les assets

Le workspace public requiert Rust 1.95.0 et edition 2024. Les assets Mermaid, Draw.io, MathJax et PlantUML sont versionnés et contrôlés par checksum ; choisissez les assets bundled ou remplacez-les par un path explicite ou un runtime défini par environnement.

Garder l'export documentaire hors de KRR

KRR rend des sources de diagrammes et de TeX déjà classifiées. L'analyse AST Markdown, l'export documentaire HTML/PDF/PNG/JPG, l'UI viewer/editor, la pagination KDV et l'export de documents relèvent du modèle, du viewer ou de l'application qui compose KRR.

Références

Cette présentation repose sur les dépôts publics au moment de l'examen. Vérifiez l'implémentation et l'utilisation dans les commits figés liés.

DépôtFichier README8654789f69d2
Références · KRR
Tous les produits