beautiful-mermaid는 AI 시대의 프로그래밍 환경에서 Mermaid 다이어그램을 시각화하는 데 필요한 아름답고 빠른 렌더링을 제공하는 TypeScript 기반 라이브러리입니다. 기존 Mermaid 렌더러의 미학적 한계, 복잡한 테마 시스템, 터미널 출력 부재, 무거운 의존성 문제를 해결하기 위해 개발되었습니다. Craft Agents의 다이어그램 기능을 강화하는 목적으로 사용되었습니다.

주요 특징:

• 5가지 다이어그램 유형 지원: Flowcharts, State, Sequence, Class, ER diagrams를 포함합니다.
• 듀얼 출력: 풍부한 UI를 위한 SVG 형식과 터미널 환경을 위한 ASCII/Unicode 형식을 모두 지원합니다.
• 테마 시스템: 15가지 내장 테마를 제공하며, 테마 커스터마이징이 매우 용이합니다. 또한, VS Code 테마 시스템인 Shiki와의 완벽한 호환성을 통해 수많은 커뮤니티 테마를 직접 활용할 수 있습니다.
• 성능: Ultra-fast 렌더링을 특징으로 하며, 100개 이상의 다이어그램을 500ms 이내에 렌더링할 수 있습니다.
• 기술 스택: 순수 TypeScript로 작성되어 Zero DOM dependencies를 가지며, 어디서든 작동합니다.

핵심 방법론: 테마 시스템 (Theming System)
beautiful-mermaid의 핵심은 강력하면서도 사용하기 쉬운 테마 시스템입니다.

• Two-Color Foundation (Mono Mode): 모든 다이어그램은 기본적으로 bg (background)와 fg (foreground) 단 두 가지 색상만으로 구성됩니다. 이 두 색상을 기반으로 CSS color-mix() 함수를 활용하여 다이어그램의 모든 요소 색상을 파생시킵니다. 예를 들어, 메인 텍스트는 fg 100%, 보조 텍스트는 fg 60%를 bg에 혼합한 색상, 커넥터는 fg 30%를 bg에 혼합한 색상, 노드 채우기는 fg 3%를 bg에 혼합한 색상 등으로 자동 계산됩니다.
• Enriched Mode: 보다 풍부한 테마를 위해 line (edge/connector), accent (arrow heads, highlights), muted (secondary text, labels), surface (node fill tint), border (node stroke)와 같은 선택적 "enrichment" 색상을 제공할 수 있습니다. 이 색상들이 제공되면 기본 color-mix() 파생 값을 오버라이드하고, 제공되지 않으면 자동으로 폴백(fallback)하여 color-mix() 파생 색상을 사용합니다.
• Live Switching: 렌더링된 SVG 요소 내의 모든 색상이 CSS custom properties로 정의됩니다. 이는 SVG를 재렌더링할 필요 없이 --bg, --fg 등의 CSS 변수 값을 변경하는 것만으로 실시간으로 테마를 전환할 수 있음을 의미합니다.
• Shiki Compatibility: fromShikiTheme() 함수를 통해 Shiki 테마 객체에서 다이어그램 색상을 추출할 수 있습니다. 이 함수는 Shiki 테마의 editor.background를 bg로, editor.foreground를 fg로, editorLineNumber.foreground 또는 focusBorder / keyword token을 accent로, comment token을 muted로, editor.selectionBackground를 surface로, editorWidget.border를 border로 지능적으로 매핑하여 다이어그램에 적용 가능한 색상 팔레트를 생성합니다.

API 및 사용법:

• SVG 렌더링: renderMermaid(text, options?) 비동기 함수를 사용하여 Mermaid 다이어그램 소스 코드를 SVG 문자열로 렌더링합니다. options 객체는 bg, fg, line, accent 등 다양한 색상 및 font, transparent 설정을 포함합니다.
• ASCII 렌더링: renderMermaidAscii(text, options?) 동기 함수를 사용하여 다이어그램을 ASCII 또는 Unicode 박스 드로잉 문자로 렌더링합니다. options는 useAscii (ASCII 모드 활성화), paddingX, paddingY, boxBorderPadding과 같은 ASCII/Unicode 출력 설정을 포함합니다.

이 라이브러리는 Alexander Grooff의 mermaid-ascii 프로젝트를 Go 언어에서 TypeScript로 포팅하고, Sequence, Class, ER 다이어그램 지원 및 Unicode 박스 드로잉, 구성 가능한 간격 및 패딩을 추가하여 확장했습니다. MIT 라이선스 하에 배포됩니다.