@grethel-labs/excaliplant 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +30 -19
  2. package/SECURITY.md +70 -0
  3. package/THIRD_PARTY_NOTICES.md +29 -0
  4. package/assets/fonts/Excalifont-Regular.woff2 +0 -0
  5. package/assets/fonts/LICENSE.txt +20 -0
  6. package/bin/excaliplant.mjs +263 -0
  7. package/index.mjs +47 -17
  8. package/package.json +34 -6
  9. package/src/layout/elk_layout.mjs +141 -19
  10. package/src/layout/sequence_layout.mjs +21 -7
  11. package/src/layout/sizing.mjs +71 -11
  12. package/src/model/diagram.mjs +317 -64
  13. package/src/parser/component_context.mjs +108 -27
  14. package/src/parser/engine.mjs +47 -37
  15. package/src/parser/plantuml.mjs +47 -22
  16. package/src/parser/plugins/component/connections.mjs +10 -2
  17. package/src/parser/plugins/component/containers.mjs +8 -3
  18. package/src/parser/plugins/component/notes.mjs +25 -9
  19. package/src/parser/plugins/component/preamble.mjs +8 -0
  20. package/src/parser/plugins/component/shapes.mjs +36 -7
  21. package/src/parser/plugins/sequence/messages.mjs +8 -2
  22. package/src/parser/plugins/sequence/notes.mjs +30 -2
  23. package/src/parser/plugins/sequence/participants.mjs +6 -1
  24. package/src/parser/plugins/sequence/preamble.mjs +4 -0
  25. package/src/parser/sequence_context.mjs +69 -8
  26. package/src/parser/utils.mjs +129 -28
  27. package/src/render/canvas_svg.mjs +30 -9
  28. package/src/render/excalidraw.mjs +847 -276
  29. package/src/render/png.mjs +21 -3
  30. package/src/render/rng.mjs +52 -0
  31. package/src/render/schema.mjs +35 -0
  32. package/src/render/sequence_render.mjs +213 -83
  33. package/src/render/svg.mjs +149 -44
  34. package/src/style/colors.mjs +63 -2
  35. package/src/style/font.mjs +62 -0
  36. package/src/style/text.mjs +73 -11
package/README.md CHANGED
@@ -1,7 +1,13 @@
1
1
 
2
2
  # excaliplant
3
3
 
4
- > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.  ·  **v0.1.3**  ·  73 tests  ·  MIT
4
+ [![npm](https://img.shields.io/npm/v/@grethel-labs/excaliplant.svg?label=latest)](https://www.npmjs.com/package/@grethel-labs/excaliplant)
5
+ [![downloads](https://img.shields.io/npm/dm/@grethel-labs/excaliplant.svg)](https://www.npmjs.com/package/@grethel-labs/excaliplant)
6
+ [![ci](https://github.com/grethel-labs/excaliplant/actions/workflows/ci.yml/badge.svg)](https://github.com/grethel-labs/excaliplant/actions/workflows/ci.yml)
7
+ [![node](https://img.shields.io/node/v/@grethel-labs/excaliplant.svg)](https://nodejs.org)
8
+ [![license](https://img.shields.io/npm/l/@grethel-labs/excaliplant.svg)](./LICENSE)
9
+
10
+ > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.  ·  **v0.2.0**  ·  78 tests  ·  MIT
5
11
 
6
12
  `@grethel-labs/excaliplant` takes PlantUML source, runs it through a plugin-based
7
13
  parser, lays it out with [ELK](https://github.com/kieler/elkjs), and
@@ -13,11 +19,11 @@ artefacts.
13
19
  <table>
14
20
  <tr>
15
21
  <td align="center" width="50%">
16
- <a href="docs/ressources/generated/png/modules.png"><img src="docs/ressources/generated/png/modules.png" alt="Module structure" width="380"/></a><br/>
22
+ <a href="docs/ressources/generated/svg/modules.svg"><img src="docs/ressources/generated/svg/modules.svg" alt="Module structure" width="380"/></a><br/>
17
23
  <sub><b>Module structure</b> — rendered by excaliplant itself</sub>
18
24
  </td>
19
25
  <td align="center" width="50%">
20
- <a href="docs/ressources/generated/png/sequence.png"><img src="docs/ressources/generated/png/sequence.png" alt="renderPlantUml flow" width="380"/></a><br/>
26
+ <a href="docs/ressources/generated/svg/sequence.svg"><img src="docs/ressources/generated/svg/sequence.svg" alt="renderPlantUml flow" width="380"/></a><br/>
21
27
  <sub><b>renderPlantUml flow</b> — rendered by excaliplant itself</sub>
22
28
  </td>
23
29
  </tr>
@@ -96,7 +102,7 @@ Lower-level entry points are also exported:
96
102
  npm test
97
103
  ```
98
104
 
99
- Ships with **73 tests** across functional, edge-case,
105
+ Ships with **78 tests** across functional, edge-case,
100
106
  security (XSS / ReDoS / prototype-pollution), and self-introspection
101
107
  suites.
102
108
 
@@ -111,7 +117,7 @@ JSDoc tags.
111
117
 
112
118
  ### Module structure
113
119
 
114
- ![Module structure](docs/ressources/generated/png/modules.png)
120
+ ![Module structure](docs/ressources/generated/svg/modules.svg)
115
121
 
116
122
  _Sources: [PlantUML](docs/ressources/generated/puml/modules.puml) · [SVG](docs/ressources/generated/svg/modules.svg)_
117
123
 
@@ -122,7 +128,7 @@ each plugin handling one PlantUML construct.
122
128
 
123
129
  ### renderPlantUml flow
124
130
 
125
- ![renderPlantUml flow](docs/ressources/generated/png/sequence.png)
131
+ ![renderPlantUml flow](docs/ressources/generated/svg/sequence.svg)
126
132
 
127
133
  _Sources: [PlantUML](docs/ressources/generated/puml/sequence.puml) · [SVG](docs/ressources/generated/svg/sequence.svg)_
128
134
 
@@ -141,7 +147,7 @@ The call graph for `renderPlantUml(text)` walks three subsystems:
141
147
 
142
148
  ### Parser plugins
143
149
 
144
- ![Parser plugins](docs/ressources/generated/png/plugins.png)
150
+ ![Parser plugins](docs/ressources/generated/svg/plugins.svg)
145
151
 
146
152
  _Sources: [PlantUML](docs/ressources/generated/puml/plugins.puml) · [SVG](docs/ressources/generated/svg/plugins.svg)_
147
153
 
@@ -175,10 +181,17 @@ PlantUML text
175
181
 
176
182
  ```text
177
183
  excaliplant
184
+ ├── assets
185
+ │ └── fonts
186
+ │ ├── Excalifont-Regular.woff2
187
+ │ └── LICENSE.txt
188
+ ├── bin
189
+ │ └── excaliplant.mjs
178
190
  ├── docs
179
191
  │ ├── ressources
180
192
  │ ├── scripts
181
193
  │ │ ├── build-docs.mjs
194
+ │ │ ├── check-build-manifest.mjs
182
195
  │ │ ├── config.mjs
183
196
  │ │ ├── extract-docs.mjs
184
197
  │ │ ├── file-tree.mjs
@@ -186,6 +199,9 @@ excaliplant
186
199
  │ └── README.template.md.njk
187
200
  ├── scripts
188
201
  │ ├── auto-patch-deps.mjs
202
+ │ ├── bump-release-version.mjs
203
+ │ ├── prepublish-guard.mjs
204
+ │ ├── setup-merge-drivers.mjs
189
205
  │ └── smoke.mjs
190
206
  ├── src
191
207
  │ ├── layout
@@ -207,10 +223,13 @@ excaliplant
207
223
  │ │ ├── canvas_svg.mjs
208
224
  │ │ ├── excalidraw.mjs
209
225
  │ │ ├── png.mjs
226
+ │ │ ├── rng.mjs
227
+ │ │ ├── schema.mjs
210
228
  │ │ ├── sequence_render.mjs
211
229
  │ │ └── svg.mjs
212
230
  │ └── style
213
231
  │ ├── colors.mjs
232
+ │ ├── font.mjs
214
233
  │ └── text.mjs
215
234
  ├── tests
216
235
  │ ├── edge_cases.test.mjs
@@ -220,6 +239,8 @@ excaliplant
220
239
  │ └── self_introspection.test.mjs
221
240
  ├── LICENSE
222
241
  ├── README.md
242
+ ├── SECURITY.md
243
+ ├── THIRD_PARTY_NOTICES.md
223
244
  ├── index.mjs
224
245
  ├── package.json
225
246
  ├── tsconfig.json
@@ -266,16 +287,6 @@ PlantUML syntax; that lives entirely in plugins. Block plugins
266
287
  (multi-line notes, class bodies) take exclusive ownership of
267
288
  subsequent lines until they release.
268
289
 
269
- Plugin contract:
270
-
271
- ```js
272
- {
273
- name,
274
- tryStart?(line, ctx): null | { onLine, tryEnd },
275
- tryLine?(line, ctx): boolean,
276
- }
277
- ```
278
-
279
290
  ### render
280
291
 
281
292
  Emits Excalidraw JSON. Each model shape is dispatched to a
@@ -283,8 +294,8 @@ dedicated `renderXxx()` function that produces one or more
283
294
  Excalidraw primitive elements (rectangle, ellipse, line, arrow,
284
295
  text). The output document is a stand-alone `.excalidraw` file
285
296
  that any Excalidraw front-end can open. The companion module
286
- [`src/render/svg.mjs`](./src/render/svg.mjs) converts the same
287
- JSON to SVG for the build-time documentation pipeline.
297
+ `src/render/svg.mjs` converts the same JSON to SVG for the
298
+ build-time documentation pipeline.
288
299
 
289
300
  ## License
290
301
 
package/SECURITY.md ADDED
@@ -0,0 +1,70 @@
1
+ # Security policy
2
+
3
+ `@grethel-labs/excaliplant` parses untrusted PlantUML text and emits
4
+ Excalidraw JSON / SVG / PNG. We treat the parser surface as a trust
5
+ boundary and ship a dedicated security test suite
6
+ ([`tests/security.test.mjs`](tests/security.test.mjs)) covering XSS,
7
+ ReDoS, prototype pollution, deeply nested input, oversized input, null
8
+ bytes, RTL override / zero-width characters, surrogate pairs, and
9
+ filesystem isolation.
10
+
11
+ ## Supported versions
12
+
13
+ We support **the latest published minor** on npm. Older lines do not
14
+ receive backports.
15
+
16
+ | Version | Supported |
17
+ | ------- | ------------------ |
18
+ | `0.1.x` | :white_check_mark: |
19
+
20
+ ## Reporting a vulnerability
21
+
22
+ Please **do not** open a public issue.
23
+
24
+ 1. Use GitHub's [private vulnerability reporting](https://github.com/grethel-labs/excaliplant/security/advisories/new).
25
+ 2. Include a minimal PlantUML reproducer if possible.
26
+
27
+ We aim to acknowledge reports within 5 working days and to ship a
28
+ patched release within 30 days for confirmed high/critical issues.
29
+
30
+ ## Disclosure policy
31
+
32
+ - Confirmed vulnerabilities are tracked as GitHub Security Advisories.
33
+ - A CVE is requested for any issue with a CVSS ≥ 7.0.
34
+ - Fixes ship as a patch release on npm; the advisory is published
35
+ simultaneously.
36
+
37
+ ## Hardening recommendations for consumers
38
+
39
+ - Treat `renderPlantUml(input)` like any other untrusted-input parser.
40
+ Run it inside a worker / isolated process if your input source is
41
+ hostile.
42
+ - The SVG output **inlines the Excalifont woff2** as a `data:` URL.
43
+ Some sandboxing environments restrict data URLs in fonts; if that
44
+ applies, post-process the SVG to drop the `<style>` block.
45
+ - The PNG path uses `@resvg/resvg-js` which executes as native code
46
+ (Rust → N-API). Keep that dependency on `npm audit` watch.
47
+
48
+ ## Built-in hardening
49
+
50
+ These limits are enforced automatically and don't need to be enabled:
51
+
52
+ - **CLI stdin / file input cap**: `bin/excaliplant.mjs` rejects input
53
+ larger than `--max-input-bytes` (default 10 MiB, ceiling 200 MiB).
54
+ - **Render-width bounds**: PNG and canvas-SVG widths are clamped to
55
+ `[16, 16000]` px to bound `@resvg/resvg-js` memory.
56
+ - **Stack-trace gating**: the CLI prints a one-line error by default.
57
+ Set `DEBUG=1` to opt back into full stack traces.
58
+ - **No install scripts**: the npm package declares no
59
+ `pre/install/postinstall` hooks; nothing executes at `npm install`
60
+ time beyond the bundled JS being placed on disk.
61
+ - **Provenance**: releases are published with `npm publish
62
+ --provenance`. Consumers can verify the package origin via
63
+ `npm audit signatures`.
64
+ - **Pinned third-party Actions**: `softprops/action-gh-release` and
65
+ `peaceiris/actions-gh-pages` are pinned by commit SHA in
66
+ `.github/workflows/release.yml`.
67
+ - **Auto-patch dependency PRs require human review**: the
68
+ `auto-patch-deps` workflow opens a PR but no longer auto-merges, so
69
+ a malicious patch release that passes audit/tests still cannot land
70
+ on `main` without an approving review.
@@ -0,0 +1,29 @@
1
+ # Third-party notices
2
+
3
+ This package bundles or depends on the following third-party works.
4
+
5
+ ---
6
+
7
+ ## Excalifont (Latin subset, woff2)
8
+
9
+ - Path: [`assets/fonts/Excalifont-Regular.woff2`](assets/fonts/Excalifont-Regular.woff2)
10
+ - Upstream: <https://github.com/excalidraw/excalidraw>
11
+ - License: SIL Open Font License 1.1 (OFL-1.1)
12
+ - Reproduction of the OFL notice is bundled alongside the binary at
13
+ [`assets/fonts/LICENSE.txt`](assets/fonts/LICENSE.txt).
14
+
15
+ The font is embedded into exported SVG / PNG documents as a `data:`
16
+ URL so they render with the same hand-drawn Excalidraw look in any
17
+ context (GitHub README rendering, sandboxed `<img>` hosts, …).
18
+
19
+ ---
20
+
21
+ ## Runtime dependencies
22
+
23
+ | Package | License | Purpose |
24
+ | ----------------- | ------- | --------------------------------- |
25
+ | `elkjs` | EPL-2.0 | Layered + orthogonal graph layout |
26
+ | `@resvg/resvg-js` | MPL-2.0 | SVG → PNG rasterisation |
27
+ | `roughjs` | MIT | Hand-drawn stroke generation |
28
+
29
+ Run `npm ls --omit=dev` for the resolved versions in your install.
@@ -0,0 +1,20 @@
1
+ Excalifont
2
+ ==========
3
+
4
+ The Excalifont woff2 font file in this directory is bundled into
5
+ @grethel-labs/excaliplant so SVG and PNG exports render text in the
6
+ same hand-drawn typeface that Excalidraw uses on screen.
7
+
8
+ Origin: https://github.com/excalidraw/excalidraw (packages/excalidraw/fonts/Excalifont)
9
+ License: SIL Open Font License, Version 1.1 (OFL-1.1)
10
+ https://scripts.sil.org/OFL
11
+
12
+ Copyright (c) 2024 by Excalidraw. All rights reserved.
13
+ Excalifont is a trademark of Excalidraw.
14
+
15
+ Manufacturer/designer:
16
+ - Your Own Font Foundry (Virgil)
17
+ - Ján Filípek / DizajnDesign (Excalifont, modifications)
18
+
19
+ The font is redistributed under the OFL-1.1; see the upstream LICENSE
20
+ for the full text. This bundling is permitted by §2 of the OFL.
@@ -0,0 +1,263 @@
1
+ #!/usr/bin/env node
2
+ // excaliplant CLI.
3
+ //
4
+ // Usage:
5
+ // excaliplant [--svg|--png|--excalidraw] [-o <out>] [--width N] [<input>]
6
+ //
7
+ // If <input> is omitted, PlantUML is read from stdin.
8
+ // If -o is omitted, output is written to stdout (binary for PNG).
9
+ //
10
+ // Examples:
11
+ // excaliplant diagram.puml # excalidraw → stdout
12
+ // excaliplant -o diagram.excalidraw diagram.puml
13
+ // excaliplant --svg diagram.puml > out.svg
14
+ // cat diagram.puml | excaliplant --png -o out.png --width 4800
15
+
16
+ import { readFile, writeFile } from "node:fs/promises";
17
+ import { renderPlantUml } from "../index.mjs";
18
+
19
+ // Hard limits to keep the CLI from being weaponised as a memory bomb.
20
+ const DEFAULT_MAX_INPUT_BYTES = 10 * 1024 * 1024; // 10 MiB of PlantUML
21
+ const MAX_INPUT_BYTES_CEILING = 200 * 1024 * 1024; // hard ceiling for --max-input-bytes
22
+ const MAX_RENDER_WIDTH = 16000; // PNG/SVG canvas width upper bound
23
+ const MIN_RENDER_WIDTH = 16;
24
+
25
+ const HELP = `excaliplant — PlantUML → Excalidraw / SVG / PNG renderer.
26
+
27
+ Usage:
28
+ excaliplant [options] [<input>]
29
+
30
+ Options:
31
+ --excalidraw Emit Excalidraw JSON (default).
32
+ --svg Emit a sketchy SVG.
33
+ --png Emit a sketchy PNG.
34
+ -o, --out <f> Write to file <f> instead of stdout.
35
+ --width <n> PNG width (default 4800) / SVG canvas width (default 1200).
36
+ Clamped to [${MIN_RENDER_WIDTH}, ${MAX_RENDER_WIDTH}].
37
+ --label <s> Source label written to appState.name.
38
+ --no-canvas For --svg: emit a tightly-cropped SVG without the 4:3 letterbox.
39
+ --rng-seed <n> Override the deterministic seed (use --rng-seed=random for non-determinism).
40
+ --max-input-bytes <N>
41
+ Reject stdin/file input larger than N bytes
42
+ (default ${DEFAULT_MAX_INPUT_BYTES}, ceiling ${MAX_INPUT_BYTES_CEILING}).
43
+ -h, --help Show this message.
44
+ -v, --version Show package version.
45
+
46
+ Exit codes:
47
+ 0 success
48
+ 1 input error (oversized, parse error, render failure)
49
+ 2 CLI argument error
50
+ 64 unexpected internal error
51
+
52
+ Set DEBUG=1 to print full stack traces on failure.
53
+ `;
54
+
55
+ /**
56
+ * Print a one-line error and exit with the given code.
57
+ * @param {number} code
58
+ * @param {string} msg
59
+ * @internal
60
+ */
61
+ function die(code, msg) {
62
+ process.stderr.write(`excaliplant: ${msg}\n`);
63
+ process.exit(code);
64
+ }
65
+
66
+ /**
67
+ * Parse a CLI argument that must be a positive integer.
68
+ * @param {string} raw
69
+ * @param {string} flag
70
+ * @returns {number}
71
+ * @internal
72
+ */
73
+ function parsePositiveInt(raw, flag) {
74
+ const n = Number(raw);
75
+ if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
76
+ die(2, `${flag} expects a positive integer (got ${JSON.stringify(raw)})`);
77
+ }
78
+ return n;
79
+ }
80
+
81
+ /**
82
+ * Parse `process.argv.slice(2)` into a normalised options object.
83
+ * Validates ranges and exits with code 2 on bad input.
84
+ * @param {string[]} argv
85
+ * @returns {object}
86
+ * @internal
87
+ */
88
+ function parseArgs(argv) {
89
+ const opts = { format: "excalidraw", canvas: true, maxInputBytes: DEFAULT_MAX_INPUT_BYTES };
90
+ const positional = [];
91
+ for (let i = 0; i < argv.length; i++) {
92
+ const a = argv[i];
93
+ switch (a) {
94
+ case "--excalidraw":
95
+ opts.format = "excalidraw";
96
+ break;
97
+ case "--svg":
98
+ opts.format = "svg";
99
+ break;
100
+ case "--png":
101
+ opts.format = "png";
102
+ break;
103
+ case "-o":
104
+ case "--out":
105
+ opts.out = argv[++i];
106
+ break;
107
+ case "--width": {
108
+ const w = parsePositiveInt(argv[++i], "--width");
109
+ if (w < MIN_RENDER_WIDTH || w > MAX_RENDER_WIDTH) {
110
+ die(2, `--width out of range [${MIN_RENDER_WIDTH}, ${MAX_RENDER_WIDTH}] (got ${w})`);
111
+ }
112
+ opts.width = w;
113
+ break;
114
+ }
115
+ case "--label":
116
+ opts.label = argv[++i];
117
+ break;
118
+ case "--no-canvas":
119
+ opts.canvas = false;
120
+ break;
121
+ case "--rng-seed":
122
+ opts.rngSeed = argv[++i];
123
+ break;
124
+ case "--max-input-bytes": {
125
+ const n = parsePositiveInt(argv[++i], "--max-input-bytes");
126
+ if (n > MAX_INPUT_BYTES_CEILING) {
127
+ die(2, `--max-input-bytes exceeds ceiling ${MAX_INPUT_BYTES_CEILING}`);
128
+ }
129
+ opts.maxInputBytes = n;
130
+ break;
131
+ }
132
+ case "-h":
133
+ case "--help":
134
+ opts.help = true;
135
+ break;
136
+ case "-v":
137
+ case "--version":
138
+ opts.versionFlag = true;
139
+ break;
140
+ default:
141
+ if (a.startsWith("-")) die(2, `unknown option: ${a}`);
142
+ positional.push(a);
143
+ }
144
+ }
145
+ if (positional.length > 1) die(2, "expected at most one positional <input> path");
146
+ opts.input = positional[0];
147
+ return opts;
148
+ }
149
+
150
+ /**
151
+ * Read the PlantUML source either from the named file or from stdin,
152
+ * enforcing the configured byte cap.
153
+ * @param {string|undefined} file
154
+ * @param {number} maxBytes
155
+ * @returns {Promise<string>}
156
+ * @internal
157
+ */
158
+ async function readInput(file, maxBytes) {
159
+ if (file) {
160
+ // Stat first so we don't load multi-GB files into memory.
161
+ const { stat } = await import("node:fs/promises");
162
+ const st = await stat(file);
163
+ if (st.size > maxBytes) {
164
+ die(
165
+ 1,
166
+ `input file ${file} is ${st.size} bytes, exceeds limit ${maxBytes} (raise with --max-input-bytes)`,
167
+ );
168
+ }
169
+ return readFile(file, "utf8");
170
+ }
171
+ return new Promise((resolve, reject) => {
172
+ let total = 0;
173
+ const chunks = [];
174
+ process.stdin.on("data", (chunk) => {
175
+ total += chunk.length;
176
+ if (total > maxBytes) {
177
+ process.stdin.destroy();
178
+ reject(
179
+ new Error(
180
+ `stdin exceeded ${maxBytes} bytes (raise with --max-input-bytes); aborted at ${total}`,
181
+ ),
182
+ );
183
+ return;
184
+ }
185
+ chunks.push(chunk);
186
+ });
187
+ process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
188
+ process.stdin.on("error", reject);
189
+ });
190
+ }
191
+
192
+ /**
193
+ * CLI entry point. Wired into `bin/excaliplant.mjs` shebang.
194
+ * @returns {Promise<void>}
195
+ * @internal
196
+ */
197
+ async function main() {
198
+ const opts = parseArgs(process.argv.slice(2));
199
+ if (opts.help) {
200
+ process.stdout.write(HELP);
201
+ return;
202
+ }
203
+ if (opts.versionFlag) {
204
+ const { readFile: rf } = await import("node:fs/promises");
205
+ const url = new URL("../package.json", import.meta.url);
206
+ const pkg = JSON.parse(await rf(url, "utf8"));
207
+ process.stdout.write(`${pkg.version}\n`);
208
+ return;
209
+ }
210
+
211
+ let text;
212
+ try {
213
+ text = await readInput(opts.input, opts.maxInputBytes);
214
+ } catch (e) {
215
+ die(1, e?.message || String(e));
216
+ }
217
+
218
+ // Build deterministic / overridable RNG.
219
+ let rng;
220
+ if (opts.rngSeed === "random") {
221
+ rng = Math.random;
222
+ } else if (opts.rngSeed != null) {
223
+ const { createSeededRng } = await import("../src/render/rng.mjs");
224
+ rng = createSeededRng(Number(opts.rngSeed) >>> 0);
225
+ }
226
+
227
+ const result = renderPlantUml(text, {
228
+ sourceLabel: opts.label ?? opts.input ?? "stdin",
229
+ rng,
230
+ });
231
+
232
+ let payload;
233
+ if (opts.format === "excalidraw") {
234
+ const doc = await result;
235
+ payload = JSON.stringify(doc, null, 2);
236
+ } else if (opts.format === "svg") {
237
+ const svgOpts = { canvas: opts.canvas };
238
+ if (opts.width) svgOpts.width = opts.width;
239
+ payload = await result.toSvg(svgOpts);
240
+ } else if (opts.format === "png") {
241
+ const pngOpts = {};
242
+ if (opts.width) pngOpts.width = opts.width;
243
+ payload = await result.toPng(pngOpts);
244
+ }
245
+
246
+ if (opts.out) {
247
+ await writeFile(opts.out, payload);
248
+ } else if (opts.format === "png") {
249
+ process.stdout.write(payload);
250
+ } else {
251
+ process.stdout.write(`${payload}\n`);
252
+ }
253
+ }
254
+
255
+ main().catch((e) => {
256
+ if (process.env.DEBUG) {
257
+ console.error(e?.stack || e);
258
+ } else {
259
+ console.error(`excaliplant: ${e?.message || e}`);
260
+ console.error(" (set DEBUG=1 to see the full stack trace)");
261
+ }
262
+ process.exit(64);
263
+ });
package/index.mjs CHANGED
@@ -63,9 +63,18 @@ export {
63
63
  DEFAULT_ASPECT_RATIO,
64
64
  } from "./src/render/canvas_svg.mjs";
65
65
  export { svgToPng } from "./src/render/png.mjs";
66
+ export { EXCALIDRAW_SCHEMA, ROUNDNESS } from "./src/render/schema.mjs";
67
+ export { createSeededRng, stableHash32 } from "./src/render/rng.mjs";
66
68
  export {
67
- Box, Connection, Diagram, Plane, Subplane,
68
- Participant, Message, SequenceDiagram, SequenceNote,
69
+ Box,
70
+ Connection,
71
+ Diagram,
72
+ Plane,
73
+ Subplane,
74
+ Participant,
75
+ Message,
76
+ SequenceDiagram,
77
+ SequenceNote,
69
78
  SHAPES,
70
79
  } from "./src/model/diagram.mjs";
71
80
 
@@ -86,6 +95,8 @@ export {
86
95
  *
87
96
  * Both helpers lazily await the underlying document — so calling
88
97
  * `toSvg()` / `toPng()` directly on the unawaited result works too.
98
+ *
99
+ * @public
89
100
  */
90
101
  export class RenderResult {
91
102
  /** @param {Promise<object>} docPromise */
@@ -93,7 +104,14 @@ export class RenderResult {
93
104
  this._doc = docPromise;
94
105
  }
95
106
 
96
- /** Thenable: `await result` yields the Excalidraw JSON document. */
107
+ /**
108
+ * Thenable: `await result` yields the Excalidraw JSON document.
109
+ * @template T
110
+ * @template R
111
+ * @param {(value: object) => T | Promise<T>} [onFulfilled]
112
+ * @param {(reason: any) => R | Promise<R>} [onRejected]
113
+ * @returns {Promise<T | R>}
114
+ */
97
115
  then(onFulfilled, onRejected) {
98
116
  return this._doc.then(onFulfilled, onRejected);
99
117
  }
@@ -108,7 +126,7 @@ export class RenderResult {
108
126
  */
109
127
  async toSvg(opts = {}) {
110
128
  const doc = await this._doc;
111
- if (opts.canvas === false) return excalidrawToSvg(doc, opts);
129
+ if (/** @type {any} */ (opts).canvas === false) return excalidrawToSvg(doc, opts);
112
130
  return excalidrawJsonToCanvasSvg(doc, opts);
113
131
  }
114
132
 
@@ -137,30 +155,42 @@ export class RenderResult {
137
155
  * @param {object} [opts]
138
156
  * @param {string} [opts.sourceLabel] Forwarded to the renderer's
139
157
  * appState.name.
158
+ * @param {() => number} [opts.rng] Optional deterministic RNG.
140
159
  * @returns {RenderResult} Thenable wrapping the Excalidraw
141
160
  * JSON document.
142
161
  */
143
162
  export function renderPlantUml(plantuml, opts = {}) {
144
- return new RenderResult((async () => {
145
- const diagram = parsePlantUml(plantuml);
146
- await layoutDiagram(diagram);
147
- return exportDiagram(diagram, {
148
- sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
149
- });
150
- })());
163
+ return new RenderResult(
164
+ (async () => {
165
+ const diagram = parsePlantUml(plantuml);
166
+ await layoutDiagram(diagram);
167
+ return exportDiagram(diagram, {
168
+ sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
169
+ rng: opts.rng,
170
+ });
171
+ })(),
172
+ );
151
173
  }
152
174
 
153
175
  /**
154
176
  * Render an already-built Diagram model. Useful for callers that want
155
177
  * to bypass the PlantUML parser and feed shapes programmatically.
156
178
  *
179
+ * @param {import("./src/model/diagram.mjs").Diagram
180
+ * | import("./src/model/diagram.mjs").SequenceDiagram} diagram
181
+ * @param {object} [opts]
182
+ * @param {string} [opts.sourceLabel]
183
+ * @param {() => number} [opts.rng]
157
184
  * @returns {RenderResult}
158
185
  */
159
186
  export function renderDiagram(diagram, opts = {}) {
160
- return new RenderResult((async () => {
161
- await layoutDiagram(diagram);
162
- return exportDiagram(diagram, {
163
- sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
164
- });
165
- })());
187
+ return new RenderResult(
188
+ (async () => {
189
+ await layoutDiagram(diagram);
190
+ return exportDiagram(diagram, {
191
+ sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
192
+ rng: opts.rng,
193
+ });
194
+ })(),
195
+ );
166
196
  }