라이브러리

KatanA Render Runtime

다이어그램과 TeX 수식 source를 SVG로 변환하는 Rust 라이브러리와 CLI입니다. 공통 입출력 API로 렌더링 결과와 진단 정보를 받습니다.

다이어그램과 수식의 SVG 렌더링을 앱에 통합하는 Rust 개발자

01

구현된 기능

Mermaid, Draw.io, ZenUML, PlantUML SVG 렌더링

근거

MathJax를 통한 TeX SVG 렌더링

근거

krr CLI의 render, compare, reference-update, bench

근거

02

시작하기

  1. Rust와 README에 적힌 runtime asset을 준비하고 krr CLI를 설치합니다.
  2. Mermaid 입력 파일을 준비한 뒤 render 명령으로 SVG를 생성합니다.

Rust와 필요한 개발 도구를 준비하고, 도입 전에 링크된 README에서 환경 요구 사항을 확인하세요. 실행 예시는 기능의 시작점이며 모든 환경에서의 동작을 보장하지 않습니다.

근거
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

사용 장면

도표와 수식을 같은 계약으로 SVG화하기

Mermaid, ZenUML, Draw.io, PlantUML의 도표 source와 MathJax의 TeX를 종류가 지정된 RenderInput으로 전달합니다. KRR은 각 runtime을 선택해 SVG, 치수, viewBox, runtime 정보, 경고·오류, cache fingerprint를 포함한 RenderOutput을 반환하므로 프리뷰나 문서 표시 측은 도표 종류별 구현 없이 렌더링 결과를 다룰 수 있습니다.

진단을 포함한 수식 입력 프리뷰

MathJaxRenderer는 일반 인라인 TeX와 display 수식을 SVG로 변환하고, 잘못된 TeX나 설치되지 않은 runtime에서는 입력 문자열을 보존한 채 diagnostics.errors에 이유를 반환합니다. 렌더링 실패가 화면 전체의 실패가 되지 않게 편집 화면에서 원본 source와 진단을 보여 주는 용도에 적합합니다. 공개 테스트에서도 정상 경로는 SVG와 치수, 비정상 경로는 원본 입력·0 치수·비어 있지 않은 오류를 확인합니다.

02 / KRR

입력부터 출력까지

  1. source와 종류 입력하기

    호출 측이 RenderInput에 RenderKind, 분류된 source, RenderConfig, RenderPolicy, RenderContext를 설정합니다. KRR은 Markdown AST를 받지 않고 도표 또는 TeX 문자열을 직접 처리하는 책임을 집니다.

  2. runtime과 테마 해결하기

    RuntimePathResolver는 명시된 runtime path를 우선하고, 지정되지 않으면 Mermaid, Draw.io, MathJax의 bundled asset과 PlantUML의 versioned cache path를 해결합니다. PlantUML에서는 vendor_config의 테마와 cache directory를 읽으며 설정이 잘못되면 RenderError로 반환합니다.

  3. SVG와 진단 받기

    Renderer::render의 반환값은 RenderOutput입니다. 정상적인 도표나 수식에서는 SVG와 양의 치수를 반환하고, 입력 오류나 runtime 부재에서는 RenderError 또는 backend가 정의한 raw source와 diagnostics를 반환하므로 사용 측은 경고와 오류를 표시·기록할 수 있습니다.

03 / KRR

주요 API·CLI

Renderer::render — 렌더링 진입점
통합 진입점은 Renderer::render(&RenderInput)입니다. RenderKind와 source의 조합이 backend에 맞지 않으면 UnsupportedKind, runtime 해결 실패는 RuntimeResolution 등의 RenderError가 됩니다.
RenderOutput — SVG와 진단 결과
출력에는 svg, width, height, view_box, runtime, profile, diagnostics, cache_fingerprint가 포함됩니다. 단순한 SVG 문자열뿐 아니라 표시 치수와 재사용 판단에 필요한 메타데이터까지 받을 수 있습니다.
krr render — CLI 렌더링
CLI는 krr mermaid render, krr drawio render, krr plantuml render 형식으로 입력 파일을 처리합니다. --output, --runtime, PlantUML의 --theme·--theme-mode·--cache-dir를 지정할 수 있으며 출력 파일을 생략하면 결과를 표준 출력으로 냅니다.
비교·진단용 명령
reference-update, compare, bench는 fixture directory를 대상으로 합니다. compare의 기본 minimum score는 99.0이므로 제품 통합 시 회귀 검사 경로로 사용할 수 있지만, 이는 품질 비교 장치이며 실행 성능을 보장하는 것은 아닙니다.

04 / KRR

구체적인 예

MathJax의 잘못된 입력을 진단과 함께 다루기

Rust 측에서 RuntimePathResolver로 MathJax runtime을 해결하고 MathJaxRenderer에 RenderInput을 전달합니다. 입력을 \not_a_real_mathjax_command로 지정해도 render는 결과를 반환하며 svg는 원본 입력, width와 height는 0, diagnostics.errors는 비어 있지 않습니다. 정상적인 E = mc^2라면 SVG, viewBox, 양의 width와 height를 얻습니다.

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

통합 조건과 책임 경계

도입 전제

공개 workspace는 Rust 1.95.0, edition 2024이며 runtime asset은 Mermaid, Draw.io, MathJax, PlantUML 등의 version과 checksum을 관리합니다. 기본 asset을 사용할지, 명시 path·환경 변수로 runtime을 교체할지 운영 방식을 선택할 수 있습니다.

책임 경계

KRR은 분류된 도표·TeX source의 runtime 렌더링을 담당합니다. Markdown AST 분석, HTML/PDF/PNG/JPG 문서 export, viewer/editor UI, KDV의 pagination과 document export는 담당하지 않으므로 상위 model·viewer·앱 측에서 조합합니다.

근거

조사 시점의 공개 저장소를 바탕으로 소개합니다. 링크된 고정 커밋에서 구현과 사용 방법을 확인할 수 있습니다.

저장소읽기 안내8654789f69d2
근거 · KRR
모든 제품