{# README template — DO NOT edit README.md directly.
   Rendered to ../README.md by docs/scripts/build-docs.mjs.

   Variables provided to the template:
     - pkg          : package.json contents
     - diagrams     : array of { id, title, doc, image, puml, svg, png }
     - moduleDocs   : array of { name, body } for non-diagram doc blocks
     - imagesFormat : "png" or "svg"
     - testCount    : number of test cases discovered
     - fileTree     : ASCII file tree (string)
#}
# {{ pkg.name | replace("@grethel-labs/", "") }}

[![npm](https://img.shields.io/npm/v/{{ pkg.name }}.svg?label=latest)](https://www.npmjs.com/package/{{ pkg.name }})
[![downloads](https://img.shields.io/npm/dm/{{ pkg.name }}.svg)](https://www.npmjs.com/package/{{ pkg.name }})
[![ci](https://github.com/grethel-labs/excaliplant/actions/workflows/ci.yml/badge.svg)](https://github.com/grethel-labs/excaliplant/actions/workflows/ci.yml)
[![node](https://img.shields.io/node/v/{{ pkg.name }}.svg)](https://nodejs.org)
[![license](https://img.shields.io/npm/l/{{ pkg.name }}.svg)](./LICENSE)

> {{ pkg.description }}  ·  **v{{ pkg.version }}**  ·  {{ testCount }} tests  ·  {{ pkg.license }}

`{{ pkg.name }}` takes PlantUML source, runs it through a plugin-based
parser, lays it out with [ELK](https://github.com/kieler/elkjs), and
emits a `.excalidraw` JSON document — opening cleanly in any
Excalidraw front-end. Optional helpers convert the result to SVG or
PNG so the same pipeline can also produce static documentation
artefacts.

<table>
  <tr>
{%- for d in diagrams -%}
{%- if loop.index0 < 2 %}
    <td align="center" width="50%">
      <a href="{{ d.image }}"><img src="{{ d.image }}" alt="{{ d.title }}" width="380"/></a><br/>
      <sub><b>{{ d.title }}</b> — rendered by {{ pkg.name | replace("@grethel-labs/", "") }} itself</sub>
    </td>
{%- endif -%}
{%- endfor %}
  </tr>
</table>

> ⚠️ This README is generated. Edit
> [`docs/README.template.md.njk`](./docs/README.template.md.njk) and
> run `npm run build:docs`.

> **AI-generated project notice:** This repository, including source code,
> documentation, comments, and generated artefacts, was created almost entirely
> with AI assistance. The maintainer does not adopt every generated sentence,
> implementation detail, or artefact as a personal statement, endorsement, or
> guarantee. Review everything carefully and use the code at your own risk; the
> MIT License warranty disclaimer applies.

---

## How to use

### Install

```sh
npm install {{ pkg.name }}
```

`@resvg/resvg-js` is pulled in as a runtime dependency so the SVG and
PNG export paths work out of the box.

### Render PlantUML to an Excalidraw document

```js
import { renderPlantUml } from "{{ pkg.name }}";

const excalidraw = await renderPlantUml(plantumlText, { sourceLabel: "demo" });
// → write `excalidraw` to disk as <name>.excalidraw, or hand it to an
//   Excalidraw embed.
```

### Render to SVG / PNG

The result of `renderPlantUml(...)` is a thenable — you can `await` it
to get the Excalidraw JSON, or chain `.toSvg()` / `.toPng()` on it to
get the rasterised diagram in a single line. Both outputs keep the
hand-drawn Excalidraw look (strokes are produced via `roughjs`, the
same library Excalidraw uses internally).

```js
import { renderPlantUml } from "{{ pkg.name }}";

const svg = await renderPlantUml(plantumlText).toSvg();
const png = await renderPlantUml(plantumlText).toPng({ width: 4800 });
```

The lower-level helpers are still exported if you need them:

```js
import {
  renderPlantUml,
  excalidrawJsonToCanvasSvg,
  svgToPng,
} from "{{ pkg.name }}";

const doc = await renderPlantUml(plantumlText);
const svg = excalidrawJsonToCanvasSvg(doc, { width: 1200 });
const png = svgToPng(svg, { width: 4800 });   // 4× SVG width
```

Lower-level entry points are also exported:

| Export                          | Purpose                                          |
| ------------------------------- | ------------------------------------------------ |
| `parsePlantUml(text)`           | PlantUML → `Diagram` model                       |
| `layoutDiagram(diagram)`        | Sizing + ELK layout + edge routing               |
| `exportDiagram(diagram)`        | Diagram → Excalidraw JSON                        |
| `excalidrawToSvg(doc)`          | Excalidraw JSON → tightly-cropped SVG            |
| `excalidrawJsonToCanvasSvg(…)`  | …same, letter-boxed onto a fixed-aspect canvas   |
| `svgToPng(svg)`                 | Rasterise SVG to PNG (`@resvg/resvg-js`)         |

The complete list of exported symbols, with parameter tables and
return types, lives in [`docs/API.md`](./docs/API.md). It is
regenerated from JSDoc on every `npm run build:docs` run.

### Sequence diagram coverage

Sequence diagrams support participants (`participant`, `actor`,
`boundary`, `control`, `entity`, `database`, `collections`, `queue`),
quoted aliases in both `Name as Alias` and `Alias as "Name"` forms,
message arrows including async/reply/reverse/bidirectional variants,
notes, participant `box ... end box` groups, `ref over` references,
dividers (`== label ==`), delays (`... label ...`), spacers (`|||` /
`||45||`), `autonumber` start/stop/resume, lifecycle controls (`create`, `activate`,
`deactivate`, `destroy`) and inline message lifecycle suffixes
(`++`, `--`, `**`, `!!`). Combined fragments render for `opt`,
`loop`, `alt`/`else`, `par`/`and`, `break`, `critical`/`option`, and
`group`/`option` blocks. A small sequence `skinparam` subset maps
directly to output colours in block or compact form: `ArrowColor`,
`ParticipantBackgroundColor`, `ParticipantBorderColor`, and
`LifeLineBorderColor`; supported CSS-like `<style>` blocks safely map
participant, arrow, note, group, lifeline, divider, and activation-bar
colour properties. Graph diagrams also support a sanitized colour subset
for common `skinparam` keys and CSS-like `<style>` selectors covering
backgrounds, component-style boxes, arrows, edge labels, notes, and
containers. Shared PlantUML presentation commands such as
`title`, `caption`, `header`, `footer`, `legend`, and `mainframe`
are preserved in parsed models and rendered where supported; PlantUML
links in graph labels and sequence message labels are kept as safe
Excalidraw link metadata. Creole and legacy HTML-like label markup
degrades to readable plain text across supported diagram families,
including emphasis, headings, lists, tables, Unicode notation, and
icon placeholders.

See the full [Sequence Diagram Component Coverage](./docs/sequence-components.md) for detailed examples and support matrix.

See the generated [Diagram Module Coverage Gallery](./docs/module-coverage.md) for rendered small and complex examples across diagram modules. The gallery includes SVG artefacts for edge cases, overlap-prone layouts, functional decisions, deliberate design choices, wild feature combinations, and repo-derived examples where the diagram type naturally maps to the source tree.

### UML graph diagram coverage

Class diagrams support the common PlantUML class-family declarations
(`class`, `abstract`, `interface`, `enum`, `annotation`, `entity`,
`protocol`, `struct`, `record`, `dataclass`, and related aliases),
generic headers, `extends` / `implements`, class body members and
separators, colon member rows, implicit relationship endpoints,
inheritance, realization, composition, aggregation, dependency and
association arrows, multiplicities, member-qualified arrows,
association classes, qualified associations, packages/namespaces, notes
on classes, members and links, JSON/object display blocks, hide/show/
remove/restore filters, and sanitized graph colours/styles.

Object diagrams support object declarations, quoted aliases, field rows,
body fields, class-style relationships with implicit object endpoints,
association-object diamonds, map/associative-array tables, row anchors
via `Map::key`, row-to-object links, PERT-style map nodes, JSON display
blocks, shared graph notes/styles/presentation, and underlined object
titles in generated Excalidraw output.

Activity diagrams support the practical PlantUML activity core: beta
`:action;` flows with multiline text, start/stop/end/kill/detach,
if/else/switch/while/repeat/fork/split controls, swimlanes, partitions,
notes, connectors, goto/label, simple `-`/`*` action lists,
SDL-style stereotypes, and legacy `(*) --> "Activity"` arrows with
labels. Activity output uses the shared graph layout/rendering pipeline
for deterministic Excalidraw, SVG, and PNG artefacts.

Component diagrams support bracket and keyword component declarations,
aliases, multiline labels, optional interface endpoints, lollipop
interfaces, packages/nodes/folders/frames/clouds/databases, direction
hints, styled arrows, notes including note-on-link, presentation
metadata, hidden edges, `port` / `portin` / `portout` declarations,
`Component::port` anchors, JSON display blocks, and shared
hide/remove/restore and style handling.

Deployment diagrams support official deployment elements such as
`node`, `artifact`, `folder`, `frame`, `cloud`, `database`, `queue`,
`card`, `package`, `stack`, `storage`, `agent`, `file`, `process`,
and `action`; nested containers; aliases; bracketed long descriptions;
JSON display blocks; styled arrows; implicit node endpoints; and shared
graph notes, presentation, filters, and style handling.

State diagrams support simple and composite states, aliases, start/end,
choice, fork, join, history and deep-history pseudostates, state
descriptions, nested state blocks, orthogonal region separators, labelled
transitions, direction hints, inline colours, notes, JSON display blocks,
scale/layout controls, hide-empty-description commands, and shared graph
presentation/style handling.

Timing diagrams support PlantUML `robust`, `concise`, `binary`, `clock`,
`analog`, and `rectangle` participant declarations, aliases, participant
state lists, absolute and relative time markers, anchored times, state
changes, binary and clock waveforms, analog polylines, cross-participant
messages, duration constraints, highlights, top/bottom notes, scale and
hidden-axis controls, footbox/resource hiding directives, separators, and
safe text/colour handling on a deterministic shared time axis.

### Data, Grammar, and Math Diagram Coverage

Regex diagrams support `@startregex` sources with literal text, shorthand and
range character classes, escaped and unicode categories, groups, lookaround-like
assertion groups, anchors, alternatives, and repetition operators. They render as
bounded railroad-style graph diagrams.

EBNF diagrams support `@startebnf` rules with terminals, non-terminals,
sequences, alternatives, optional blocks, repetition blocks, grouping, special
sequences, comments/notes, and documented style/pragma lines tolerated by the
parser. They share the railroad-style graph output used by regex diagrams.

JSON diagrams support `@startjson` objects, arrays, strings, numbers, booleans,
`null`, empty objects/arrays, unicode and escape sequences through the platform
JSON parser, plus PlantUML `#highlight` paths. YAML diagrams support the
documented safe subset for mappings, sequences, scalars, symbol/unicode keys,
and `#highlight` paths. Both render nested data as deterministic graph trees.

Math support covers standalone `@startmath` / `@startlatex` formula diagrams and
inline `<math>` / `<latex>` tags in existing labels. The renderer intentionally
uses a safe readable text fallback instead of pulling in external formula
rendering dependencies.

### Network, UI, and Architecture Coverage

Network diagrams support `@startnwdiag` with `nwdiag` network lanes, address
metadata, groups, devices, multi-homed device declarations, and peer
connections. Devices render through the shared graph pipeline so labels are
measured and routed deterministically.

Salt diagrams support `@startsalt` wireframes with low-fidelity labels,
buttons, radio buttons, checkboxes, text fields, dropdowns, tabs, grid/table
rows, and textarea-style blocks. Unsupported Salt decoration degrades to safe
readable labels instead of raw markup.

Archimate diagrams support `archimate` element declarations with categories,
aliases, stereotypes, junction declarations, simple rectangle states, and
directed relationships. External sprites and stdlib-specific icons use safe
text/type fallbacks.

### Planning, Hierarchy, and Files Coverage

Gantt diagrams support `@startgantt` task declarations with durations, explicit
starts and ends, milestones, project starts, separators, and simple task
dependencies. The parser records scheduling details on deterministic task boxes
and routes dependencies through the shared graph pipeline.

Mindmap and WBS diagrams support PlantUML OrgMode-style markers, Markdown-style
heading/list input, side/direction directives, mixed `*` / `+` hierarchy
markers, and safe text handling. Files diagrams support `@startfiles` path trees
with shared folder merging and file/folder stereotypes.

Chronology diagrams support dated milestones, labelled timestamp entries, simple
ranges, start/end directives, and dependencies between events. Unsupported
calendar-specific presentation lines are tolerated so useful chronology content
still renders as safe readable timeline graphs.

### Entity Relationship Coverage

Information Engineering diagrams support PlantUML `entity` declarations with
attribute rows plus crow-foot relationship operators such as `}|..||`,
`}o..o|`, `||--o{`, and `|o--||`. Cardinality and optionality markers are kept
as endpoint labels so exported diagrams remain deterministic and reviewable.

Chen ER diagrams support `@startchen` entity, relationship, attribute,
derived-attribute, multi-valued-attribute, and key declarations, including
empty or member-bearing blocks, simple orientation directives, aliases, and
cardinality-labelled connections such as `Person -N- Birthplace`.

### Special Rendering Coverage

Ditaa diagrams support `@startditaa` blocks and inline `ditaa(...)` sources.
The parser preserves bounded ASCII canvas lines, consumes common rendering
options such as no-separator, no-shadow, and scale hints, and emits a safe
deterministic Excalidraw graph representation instead of executing an external
Ditaa renderer.

Chart diagrams support `@startchart` sources with horizontal and vertical axes,
bar, line, area, and scatter series, labels, colours, legends, orientation, and
stacking options. Series and option rows render as reviewable graph-backed
chart metadata with the same SVG escaping and layout bounds as other diagram
families.

Use-case diagrams support actor and usecase declarations in keyword,
colon, parenthesized, quoted-alias, reverse-description, stereotype, and
business `/` forms; nested `package` / `rectangle` system boundaries;
include, extend, generalization, directional, labelled, and inline-styled
relationships; notes attached to aliases or usecases; and shared graph
presentation, link, text-markup, skinparam, and `<style>` handling.

### Run the tests

```sh
npm test
```

Ships with **{{ testCount }} tests** across functional, edge-case,
security (XSS / ReDoS / prototype-pollution), and self-introspection
suites.

---

## Self-rendered architecture diagrams

The diagrams below are produced **by {{ pkg.name | replace("@grethel-labs/", "") }} itself** at build
time from PlantUML sources that describe this very repository. The
text under each image is extracted from the source via `@diagram`
JSDoc tags.
{% for d in diagrams %}
### {{ d.title }}

![{{ d.title }}]({{ d.image }})

_Sources: [PlantUML]({{ d.puml }}) · [SVG]({{ d.svg }})_

{{ d.doc | trim }}
{% endfor %}
## Pipeline

```text
PlantUML text
     │ parsePlantUml()
     ▼
  Diagram (planes, subplanes, boxes, connections)
     │ layoutDiagram()  (sizing → ELK layered + orthogonal routing → chamfer)
     ▼
  Diagram with absolute positions and edge paths
     │ exportDiagram()
     ▼
  Excalidraw JSON
     │ excalidrawJsonToCanvasSvg()  (optional)
     ▼
  SVG  ── svgToPng() ──▶  PNG  (both optional, no headless browser)
```

## Repository layout

```text
{{ fileTree }}
```

Generated artefacts (`docs/ressources/generated/`) live in
`.gitignore` — they are rebuilt by `npm run build:docs`. The
single-page API reference at [`docs/API.md`](./docs/API.md) is
generated by the same command from JSDoc.

## Module documentation
{% for m in moduleDocs %}
### {{ m.name }}

{{ m.body | trim }}
{% endfor %}
## License

{{ pkg.license }} © grethel-labs