@liminis/diagrams documentation

This is documentation for someone building a tool on top of @liminis/diagrams — a CLI, a CI job, a wiki, a different editor. It answers the questions the top-level README.md quick start doesn’t: what the layout result contains, how manual positions interact with dagre, what the parser accepts and silently discards, and which parts of a “C4 editing experience” live here versus in @liminis/editor.

There is a live demo if you would rather see it than read about it — it runs the published package, so what you drag there is what you install.

Limitations — read this first

The most expensive mistake a tool builder can make against this package is invisible until you’ve already built against it. Four things this package does not do:

1. No editing affordance. There is no textarea overlay, no click-to-edit, no layout-mode toolbar, no dark-mode auto-detection. Those are all Lexical-bound and stayed behind in @liminis/editor (C4Component.tsx). This package gives you render and drag — a host still needs its own “edit the source text” surface.
2. No persistence. @liminis/diagrams never writes anywhere. C4InteractiveRenderer reports position changes via a callback; storing them — in a file, a database, a fenced code block’s meta string, wherever — is entirely the host’s job. See Recipe 3.
3. Element IDs are fence-local. C4Element.id is unique within one parsed diagram only. It carries no identity across two diagrams — two System(app, ...) blocks in different files have nothing connecting their app IDs. Anything that wants stable cross-file identity (file#id, a declared namespace, a URN) has to establish it in a layer above this package, over several already-parsed diagrams.
4. No cross-diagram link syntax. There is no Rel that spans two diagrams, and no “this container is detailed in another diagram” relationship — which is exactly the C4 zoom-level relationship a linked set of diagrams wants. You can’t improvise one either: an unrecognized macro name is a parse error, not a silently-ignored no-op, and !include is recognized but stripped, so the included file is never fetched or inlined. Adding it means extending the parser, or carrying the link beside the diagram in fence meta or frontmatter.

Contents

Page	Answers
Architecture	Which entry point (., ./core, ./react, ./server) should I install, and why?
C4-PlantUML reference	Will my existing C4-PlantUML source parse? What gets silently stripped?
Data model	What does a parsed diagram / layout result actually contain? (the centerpiece)
Recipes	Complete, runnable examples: headless SVG rendering, embedding the interactive renderer, persisting positions.
GitHub	How do I get GitHub to show a rendered C4 diagram in a markdown file?
Claude Code	How do I get Claude to render a real C4 diagram instead of hand-drawing one?