zombie-mermaid 1.4.0 → 1.6.0

package/README.md

@@ -4,13 +4,18 @@
 
 **Render Mermaid diagrams as beautiful SVGs or ASCII art**
 
-Ultra-fast, fully themeable, zero DOM dependencies. A maintained fork of [`beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid).
+Ultra-fast, fully themeable, zero DOM dependencies. A maintained fork of [`beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid) that refuses to die.
 
-![zombie-mermaid sequence diagram example](hero.png)
+![Raw Mermaid source rendering into a themed, animated diagram, drawn by zombie-mermaid itself](hero.svg)
 
-[**Live demo →**](https://dfadler.github.io/zombie-mermaid/)
+[![Live Demo](https://img.shields.io/badge/Live_Demo-view_the_sample_gallery-1f6feb?style=for-the-badge)](https://dfadler.github.io/zombie-mermaid/)
+[![Beautiful Mermaid Fork Fixes](https://img.shields.io/badge/Beautiful_Mermaid_Fork_Fixes-before%2Fafter_evidence-1f6feb?style=for-the-badge)](https://dfadler.github.io/zombie-mermaid/fork-fixes.html)
 
 [![npm version](https://img.shields.io/npm/v/zombie-mermaid.svg)](https://www.npmjs.com/package/zombie-mermaid)
+[![CI](https://github.com/dfadler/zombie-mermaid/actions/workflows/ci.yml/badge.svg)](https://github.com/dfadler/zombie-mermaid/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/dfadler/zombie-mermaid/branch/main/graph/badge.svg)](https://codecov.io/gh/dfadler/zombie-mermaid)
+[![Bundle Size](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/dfadler/zombie-mermaid/main/badges/bundle-size.json)](#bundle-size)
+[![Socket Security](https://socket.dev/api/badge/npm/package/zombie-mermaid)](https://socket.dev/npm/package/zombie-mermaid)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 </div>
@@ -19,11 +24,13 @@ Ultra-fast, fully themeable, zero DOM dependencies. A maintained fork of [`beaut
 
 ## Why This Fork Exists
 
-`beautiful-mermaid` is a genuinely good library — see "Why We Built This" below — but upstream development has stalled: as of this writing there are 30 open pull requests, the oldest dating back over half a year, and nothing has merged in months. `zombie-mermaid` is the same codebase, kept moving: upstream fixes get pulled in, PRs stuck in the upstream queue get a home, and releases actually ship.
+`beautiful-mermaid` is a genuinely good library — fast, beautiful, and works everywhere from rich UIs to plain terminals. But upstream development has stalled: dozens of [pull requests](https://github.com/lukilabs/beautiful-mermaid/pulls) sit open, some for over half a year, and nothing has merged in months — by most definitions, it's dead. I maintain `zombie-mermaid` as the fork that won't stay buried: pulling in upstream fixes, giving PRs stuck in the upstream queue a home, and actually shipping releases. Craft and Craft Agents aren't part of this project's process going forward; this is an independently maintained continuation.
 
-It's still MIT-licensed, still built on the same foundation, and still credits the original authors below.
+This isn't just a claim — see **[what this fork fixes](https://dfadler.github.io/zombie-mermaid/fork-fixes.html)** for an evidence-based before/after showcase: every bug listed there is rendered by the actual pre-fix and post-fix code, not described from memory.
 
-## Why We Built This
+It's still MIT-licensed, still built on the same foundation, and still credits the original authors — including the ASCII rendering engine's origins — in [Attribution](#attribution) below.
+
+## The Problem With Default Mermaid Rendering
 
 Diagrams are essential for AI-assisted programming. When you're working with an AI coding assistant, being able to visualize data flows, state machines, and system architecture—directly in your terminal or chat interface—makes complex concepts instantly graspable.
 
@@ -34,9 +41,15 @@ Diagrams are essential for AI-assisted programming. When you're working with an
 - **No terminal output** — Can't render to ASCII for CLI tools
 - **Heavy dependencies** — Pulls in a lot of code for simple diagrams
 
-We built `beautiful-mermaid` at [Craft](https://craft.do) to power diagrams in [Craft Agents](https://agents.craft.do). It's fast, beautiful, and works everywhere—from rich UIs to plain terminals.
+### Bundle Size
 
-The ASCII rendering engine is based on [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) by Alexander Grooff. We ported it from Go to TypeScript and extended it. Thank you Alexander for the excellent foundation! (And inspiration that this was possible.)
+The **Bundle Size** badge above tracks the gzipped size of `zombie-mermaid`'s
+main entry point (`dist/index.js`) and updates automatically with every
+release — the same badge/CI-tracked pattern already backing the coverage and
+CI status badges. Need ASCII rendering only? `import { renderMermaidASCII }
+from 'zombie-mermaid/ascii'` skips [ELK.js](https://github.com/kieler/elkjs),
+the layout engine the SVG renderer depends on, for a substantially smaller
+bundle.
 
 ## Features
 
@@ -49,6 +62,7 @@ The ASCII rendering engine is based on [mermaid-ascii](https://github.com/Alexan
 - **Mono mode** — Beautiful diagrams from just 2 colors
 - **Zero DOM dependencies** — Pure TypeScript, works everywhere
 - **Ultra-fast** — Renders 100+ diagrams in under 500ms
+- **Accessible SVG output, CI-enforced** — every diagram type always gets a `role`-correct, nameable root `<svg>`; see the [accessibility conformance statement](docs/accessibility.md) for exactly what's guaranteed
 
 ## Installation
 
@@ -95,6 +109,16 @@ const ascii = renderMermaidASCII(`graph LR; A --> B --> C`)
 └───┘     └───┘     └───┘
 ```
 
+ASCII-only consumers (a CLI, a terminal UI, a serverless function) can import
+from `zombie-mermaid/ascii` instead of the package root. The root entry
+statically pulls in `elkjs` for the SVG layout engine — over 1.4MB minified —
+even if you never call `renderMermaidSVG`. The `/ascii` subpath never imports
+it:
+
+```typescript
+import { renderMermaidASCII } from 'zombie-mermaid/ascii'
+```
+
 Using this from React? See [React Integration](docs/react-integration.md) for a zero-flash `useMemo()` pattern.
 
 ---
@@ -115,9 +139,43 @@ zombie-mermaid --help                                   # Show all options
 
 ---
 
+## MCP Server
+
+> 🧪 **Experimental — shipped to gauge interest, not a finished or best-effort implementation.** This is a first cut covering the common case; the tool surface may change based on feedback. Try it and [open an issue](https://github.com/dfadler/zombie-mermaid/issues/new) with what you'd want from it.
+
+`zombie-mermaid mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io/) server on stdio, exposing the library's rendering as two tools: `render_mermaid_svg` and `render_mermaid_ascii`. Point an MCP client (Claude Desktop, Claude Code, or anything else that speaks MCP) at it to render Mermaid diagrams directly in a conversation, without shelling out to the CLI or importing the library.
+
+Example Claude Desktop / Claude Code MCP server config:
+
+```json
+{
+  "mcpServers": {
+    "zombie-mermaid": {
+      "command": "npx",
+      "args": ["-y", "zombie-mermaid", "mcp"]
+    }
+  }
+}
+```
+
+Both tools accept a `diagram` string plus a handful of rendering options (`theme`, `transparent`, `font` for SVG; `useAscii`, `paddingX`/`paddingY`/`boxBorderPadding` for ASCII) — see each tool's `inputSchema` for the full, current list. Invalid Mermaid syntax comes back as a normal tool error (`isError: true`) rather than crashing the connection.
+
+To embed the server in your own process instead of running it as a subcommand, import `zombie-mermaid/mcp` and connect it to any [MCP `Transport`](https://modelcontextprotocol.io/) yourself:
+
+```typescript
+import { createMcpServer } from 'zombie-mermaid/mcp'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+const server = createMcpServer()
+await server.connect(new StdioServerTransport())
+```
+
+---
+
 ## Docs
 
 - [Guides](docs/guides/) — task-oriented walkthroughs: [browsing the samples](docs/guides/samples.md), [choosing a theme](docs/guides/theming.md)
+- [Accessibility](docs/accessibility.md) — conformance statement: what's guaranteed (and CI-enforced), what's implemented but unverified by automation, and what isn't covered
 - [Theming](docs/theming.md) — the two-color foundation, enriched mode, built-in themes, custom themes, Shiki compatibility
 - [Supported Diagrams](docs/diagrams.md) — syntax for every diagram type, XY chart styling, and ASCII rendering options
 - [React Integration](docs/react-integration.md) — zero-flash rendering with `useMemo()`
@@ -130,7 +188,7 @@ More design write-ups and reference material live in [docs/](docs/).
 
 ## Attribution
 
-The ASCII rendering engine is based on [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) by Alexander Grooff. We ported it from Go to TypeScript and extended it with:
+The ASCII rendering engine is based on [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) by Alexander Grooff, ported from Go to TypeScript and extended with:
 
 - Sequence diagram support
 - Class diagram support
@@ -142,14 +200,12 @@ Thank you Alexander for the excellent foundation!
 
 ---
 
-## License
+## Contributing
 
-MIT — see [LICENSE](LICENSE) for details.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, the test/lint workflow, and how changesets and releases work ([RELEASING.md](RELEASING.md)). Security issues should go through [SECURITY.md](SECURITY.md) instead of a public issue. Released versions are tracked in [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
-<div align="center">
-
-Built with care by the team at [Craft](https://craft.do)
+## License
 
-</div>
+MIT — see [LICENSE](LICENSE) for details.