@grethel-labs/excaliplant 0.2.0 → 0.3.6

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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,100 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@grethel-labs/excaliplant` are documented in this
4
+ file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [0.3.1] - 2026-05-04
8
+
9
+ ### Fixed
10
+
11
+ - Dependabot PRs now automatically receive `release:patch` labels to ensure the
12
+ release version workflow can process them correctly.
13
+ - Auto-patch dependencies workflow now adds `release:patch` label to created/updated PRs.
14
+ - PR release version workflow detects Dependabot PRs and automatically adds
15
+ `release:patch` label if missing.
16
+ - Type-checking now narrows the component-context container stack via a proper
17
+ discriminated union, fixing strict null/undefined errors surfaced by
18
+ TypeScript 6.x.
19
+ - `declareParticipant` resolves the cached lookup once so its return type is a
20
+ non-nullable `Participant`, satisfying stricter type checking.
21
+ - Docs file-tree script imports `tree-node-cli` namespace-style and picks the
22
+ named export (v3+) or default (v1.x) at runtime, so the docs build works
23
+ across both major versions.
24
+
25
+ ### Added
26
+
27
+ - New `auto-rebase-prs.yml` workflow that automatically rebases open PRs
28
+ when main is updated, and adjusts version numbers if there are conflicts
29
+ from parallel PRs being merged.
30
+
31
+ ## [0.3.0] - 2026-05-04
32
+
33
+ ### Added
34
+
35
+ - Repository-wide editing-agent instructions via `AGENTS.md`, with thin adapter
36
+ files for GitHub Copilot, Claude Code, Gemini CLI, Cursor, Windsurf, Cline,
37
+ and Roo Code. The adapters all point back to `AGENTS.md` so project rules stay
38
+ centralized for future automated editing workflows.
39
+ - A README notice clarifying that the repository was created almost entirely
40
+ with AI assistance and that use remains at the user's own risk under the MIT
41
+ License warranty disclaimer.
42
+
43
+ ## [0.2.1] - 2026-05-03
44
+
45
+ ### Security
46
+
47
+ - `excalidrawJsonToCanvasSvg`: HTML-escape the user-supplied `background`
48
+ option before interpolating it into the canvas `<rect>` `fill`
49
+ attribute. Previously a string like `'" onload="alert(1)'` could
50
+ break out of the attribute and inject arbitrary markup into the
51
+ emitted SVG. The escape uses the same routine as the rest of
52
+ `src/render/svg.mjs` (`escapeAttr`, now exported) and now also
53
+ escapes `>` for defence in depth.
54
+ - `parsePlantUml` gains opt-in resource limits
55
+ (`maxInputBytes`, `maxLines`, `maxNodes`, `maxEdges`) with sensible
56
+ defaults so the library API enforces the same safety bounds as the
57
+ CLI. `renderPlantUml({ limits })` forwards the option.
58
+ - CI permissions are now `contents: read` by default; only the
59
+ PR-docs auto-amend job re-asserts `contents: write`. The release
60
+ workflow additionally runs `typecheck`, `format:check`, an
61
+ `npm audit --omit=dev --audit-level=high`, and a pack + smoke
62
+ install before publishing.
63
+
64
+ ### Fixed
65
+
66
+ - `slug()` keeps Unicode letters and digits instead of replacing
67
+ every non-ASCII character with `_`. Diagrams with German umlauts,
68
+ Japanese identifiers, etc. now resolve their connections correctly.
69
+ - `stripComment()` is now string-aware: an apostrophe inside a
70
+ `"..."` literal no longer truncates the line, so labels like
71
+ `"Bob 's service"` parse intact.
72
+ - Component connections that use bracket / paren / quoted shorthand
73
+ (`[Foo] --> [Bar]`, `(Use case A) --> (Use case B)`) now resolve
74
+ to the matching declared boxes regardless of capitalisation or
75
+ Unicode content.
76
+ - Sequence diagrams interleave notes between messages by declaration
77
+ order. Previously every note was placed below the last message,
78
+ losing temporal context.
79
+
80
+ ### Added
81
+
82
+ - `parsePlantUml(text, { unknownLines: "warn" | "strict" })` for
83
+ diagnostics on lines that no plugin consumed (default behaviour
84
+ remains silent for backwards compatibility).
85
+ - `runEngine({ onUnknownLine })` callback so custom pipelines can
86
+ observe unrecognised input.
87
+ - `DEFAULT_PARSE_LIMITS` is exported from the top-level module and
88
+ from `./parser/plantuml`.
89
+ - `CHANGELOG.md` (this file) and a tightened `pre-commit` hook that
90
+ also runs `npm run typecheck`.
91
+
92
+ ### Changed
93
+
94
+ - `prepublishOnly` now runs `npm test`, `npm run typecheck`,
95
+ `npm run format:check`, and `npm run build` (in addition to the
96
+ existing prepublish guard) before publishing.
97
+
98
+ ## [0.2.0] - 2026-04
99
+
100
+ Initial public release on npm.
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  [![node](https://img.shields.io/node/v/@grethel-labs/excaliplant.svg)](https://nodejs.org)
8
8
  [![license](https://img.shields.io/npm/l/@grethel-labs/excaliplant.svg)](./LICENSE)
9
9
 
10
- > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. &nbsp;·&nbsp; **v0.2.0** &nbsp;·&nbsp; 78 tests &nbsp;·&nbsp; MIT
10
+ > PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser. &nbsp;·&nbsp; **v0.3.6** &nbsp;·&nbsp; 86 tests &nbsp;·&nbsp; MIT
11
11
 
12
12
  `@grethel-labs/excaliplant` takes PlantUML source, runs it through a plugin-based
13
13
  parser, lays it out with [ELK](https://github.com/kieler/elkjs), and
@@ -33,6 +33,13 @@ artefacts.
33
33
  > [`docs/README.template.md.njk`](./docs/README.template.md.njk) and
34
34
  > run `npm run build:docs`.
35
35
 
36
+ > **AI-generated project notice:** This repository, including source code,
37
+ > documentation, comments, and generated artefacts, was created almost entirely
38
+ > with AI assistance. The maintainer does not adopt every generated sentence,
39
+ > implementation detail, or artefact as a personal statement, endorsement, or
40
+ > guarantee. Review everything carefully and use the code at your own risk; the
41
+ > MIT License warranty disclaimer applies.
42
+
36
43
  ---
37
44
 
38
45
  ## How to use
@@ -102,7 +109,7 @@ Lower-level entry points are also exported:
102
109
  npm test
103
110
  ```
104
111
 
105
- Ships with **78 tests** across functional, edge-case,
112
+ Ships with **86 tests** across functional, edge-case,
106
113
  security (XSS / ReDoS / prototype-pollution), and self-introspection
107
114
  suites.
108
115
 
@@ -237,6 +244,11 @@ excaliplant
237
244
  │ ├── plantuml.test.mjs
238
245
  │ ├── security.test.mjs
239
246
  │ └── self_introspection.test.mjs
247
+ ├── AGENTS.md
248
+ ├── CHANGELOG.md
249
+ ├── CLAUDE.md
250
+ ├── CONTRIBUTING.md
251
+ ├── GEMINI.md
240
252
  ├── LICENSE
241
253
  ├── README.md
242
254
  ├── SECURITY.md
package/SECURITY.md CHANGED
@@ -10,12 +10,10 @@ filesystem isolation.
10
10
 
11
11
  ## Supported versions
12
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: |
13
+ The **current release on npm — including the latest patch — is fully
14
+ supported**. Older versions may still work, but can show reduced
15
+ functionality, missing fixes, or unaddressed advisories. Please upgrade
16
+ to the latest version before reporting a vulnerability.
19
17
 
20
18
  ## Reporting a vulnerability
21
19
 
package/index.mjs CHANGED
@@ -53,7 +53,7 @@ import { excalidrawToSvg } from "./src/render/svg.mjs";
53
53
  import { excalidrawJsonToCanvasSvg } from "./src/render/canvas_svg.mjs";
54
54
  import { svgToPng } from "./src/render/png.mjs";
55
55
 
56
- export { parsePlantUml } from "./src/parser/plantuml.mjs";
56
+ export { parsePlantUml, DEFAULT_PARSE_LIMITS } from "./src/parser/plantuml.mjs";
57
57
  export { layoutDiagram } from "./src/layout/elk_layout.mjs";
58
58
  export { exportDiagram } from "./src/render/excalidraw.mjs";
59
59
  export { excalidrawToSvg } from "./src/render/svg.mjs";
@@ -156,13 +156,15 @@ export class RenderResult {
156
156
  * @param {string} [opts.sourceLabel] Forwarded to the renderer's
157
157
  * appState.name.
158
158
  * @param {() => number} [opts.rng] Optional deterministic RNG.
159
+ * @param {Partial<import("./src/parser/plantuml.mjs").DEFAULT_PARSE_LIMITS>} [opts.limits]
160
+ * Optional resource limits forwarded to {@link parsePlantUml}.
159
161
  * @returns {RenderResult} Thenable wrapping the Excalidraw
160
162
  * JSON document.
161
163
  */
162
164
  export function renderPlantUml(plantuml, opts = {}) {
163
165
  return new RenderResult(
164
166
  (async () => {
165
- const diagram = parsePlantUml(plantuml);
167
+ const diagram = parsePlantUml(plantuml, { limits: opts.limits });
166
168
  await layoutDiagram(diagram);
167
169
  return exportDiagram(diagram, {
168
170
  sourceLabel: opts.sourceLabel ?? diagram.title ?? "",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@grethel-labs/excaliplant",
3
- "version": "0.2.0",
3
+ "version": "0.3.6",
4
4
  "description": "PlantUML → ELK layout → Excalidraw renderer with a plugin-based parser.",
5
5
  "type": "module",
6
6
  "main": "index.mjs",
@@ -13,6 +13,7 @@
13
13
  "src/",
14
14
  "assets/fonts/",
15
15
  "README.md",
16
+ "CHANGELOG.md",
16
17
  "LICENSE",
17
18
  "SECURITY.md",
18
19
  "THIRD_PARTY_NOTICES.md"
@@ -40,7 +41,7 @@
40
41
  "format": "prettier --write .",
41
42
  "format:check": "prettier --check .",
42
43
  "prepare": "husky && node scripts/setup-merge-drivers.mjs",
43
- "prepublishOnly": "node scripts/prepublish-guard.mjs && npm test && npm run build"
44
+ "prepublishOnly": "node scripts/prepublish-guard.mjs && npm test && npm run typecheck && npm run format:check && npm run build"
44
45
  },
45
46
  "lint-staged": {
46
47
  "*.{mjs,js,cjs,ts,json,yml,yaml,md}": "prettier --write"
@@ -81,8 +82,8 @@
81
82
  "lint-staged": "^16.4.0",
82
83
  "nunjucks": "^3.2.4",
83
84
  "prettier": "^3.8.3",
84
- "tree-node-cli": "^1.6.0",
85
+ "tree-node-cli": "^3.0.0",
85
86
  "typedoc": "^0.28.19",
86
- "typescript": "^5.6.0"
87
+ "typescript": "^6.0.3"
87
88
  }
88
89
  }
@@ -58,19 +58,20 @@ export function layoutSequenceDiagram(diagram) {
58
58
  for (const p of diagram.participants) p.lifelineTop = lifelineTop;
59
59
 
60
60
  // 3. Walk messages and notes in their declaration order, assigning y.
61
- // We interleave them by relying on the parser's declaration order. The
62
- // model only has separate lists, so we just place messages first, then
63
- // notes near the most recent message (good-enough heuristic).
64
- let y = lifelineTop + MESSAGE_FIRST_Y;
65
- for (const m of diagram.messages) {
66
- m.y = y;
67
- y += m.isSelf ? SELF_HEIGHT + MESSAGE_GAP : MESSAGE_GAP;
68
- }
61
+ // Both message and note objects carry a `seq` index assigned by the
62
+ // sequence context; we merge the two streams on that field so notes
63
+ // appear at the temporal position they were declared at, instead of
64
+ // being dumped at the bottom of the diagram.
65
+ const timeline = [
66
+ ...diagram.messages.map((m) => ({ kind: "msg", item: m, seq: m.seq ?? Infinity })),
67
+ ...diagram.notes.map((n) => ({ kind: "note", item: n, seq: n.seq ?? Infinity })),
68
+ ];
69
+ // Stable sort by declaration index. Items without a `seq` (e.g.
70
+ // programmatically-built diagrams) keep their relative order at the
71
+ // tail.
72
+ timeline.sort((a, b) => a.seq - b.seq);
69
73
 
70
- // Notes: place them between messages along the same y-axis, spaced
71
- // after the last message. This is a pragmatic placement; a future
72
- // pass could weave them into the message timeline based on parser
73
- // index.
74
+ // Pre-size notes so we know their height before assigning y.
74
75
  for (const n of diagram.notes) {
75
76
  const lines = n.text.split("\n");
76
77
  n.width = Math.max(
@@ -78,20 +79,31 @@ export function layoutSequenceDiagram(diagram) {
78
79
  Math.max(...lines.map((l) => measureLine(l, FONT.sizeDescription).width)) + NOTE_PAD * 2,
79
80
  );
80
81
  n.height = lines.length * FONT.sizeDescription * FONT.lineHeight + NOTE_PAD * 2;
81
- if (n.side === "over" && n.target2) {
82
- const x1 = Math.min(n.target.x, n.target2.x);
83
- const x2 = Math.max(n.target.x, n.target2.x);
84
- n.x = (x1 + x2) / 2 - n.width / 2;
85
- } else if (n.side === "left") {
86
- n.x = n.target.x - n.target.headWidth / 2 - n.width - NOTE_GAP;
87
- } else if (n.side === "right") {
88
- n.x = n.target.x + n.target.headWidth / 2 + NOTE_GAP;
82
+ }
83
+
84
+ let y = lifelineTop + MESSAGE_FIRST_Y;
85
+ for (const entry of timeline) {
86
+ if (entry.kind === "msg") {
87
+ const m = /** @type {import("../model/diagram.mjs").Message} */ (entry.item);
88
+ m.y = y;
89
+ y += m.isSelf ? SELF_HEIGHT + MESSAGE_GAP : MESSAGE_GAP;
89
90
  } else {
90
- // over single
91
- n.x = n.target.x - n.width / 2;
91
+ const n = /** @type {import("../model/diagram.mjs").SequenceNote} */ (entry.item);
92
+ if (n.side === "over" && n.target2) {
93
+ const x1 = Math.min(n.target.x, n.target2.x);
94
+ const x2 = Math.max(n.target.x, n.target2.x);
95
+ n.x = (x1 + x2) / 2 - n.width / 2;
96
+ } else if (n.side === "left") {
97
+ n.x = n.target.x - n.target.headWidth / 2 - n.width - NOTE_GAP;
98
+ } else if (n.side === "right") {
99
+ n.x = n.target.x + n.target.headWidth / 2 + NOTE_GAP;
100
+ } else {
101
+ // over single
102
+ n.x = n.target.x - n.width / 2;
103
+ }
104
+ n.y = y;
105
+ y += n.height + NOTE_GAP;
92
106
  }
93
- n.y = y;
94
- y += n.height + NOTE_GAP;
95
107
  }
96
108
 
97
109
  const lifelineBottom = y + BOTTOM_MARGIN;
@@ -371,6 +371,8 @@ export class Message {
371
371
  this.startArrowhead = startArrowhead;
372
372
  this.endArrowhead = endArrowhead;
373
373
  this.y = 0;
374
+ /** Declaration order index across messages + notes. */
375
+ this.seq = -1;
374
376
  }
375
377
  /** @returns {boolean} `true` when sender and receiver are the same lifeline. */
376
378
  get isSelf() {
@@ -402,6 +404,8 @@ export class SequenceNote {
402
404
  this.y = 0;
403
405
  this.width = 0;
404
406
  this.height = 0;
407
+ /** Declaration order index across messages + notes. */
408
+ this.seq = -1;
405
409
  }
406
410
  }
407
411
 
@@ -29,7 +29,7 @@ import { planeColor, subplaneColor } from "../style/colors.mjs";
29
29
  */
30
30
  export function createComponentContext() {
31
31
  const diagram = new Diagram();
32
- /** @type {Array<{kind:'plane'|'subplane', plane?:Plane, subplane?:Subplane, id:string}>} */
32
+ /** @type {Array<{kind:'plane', plane:Plane, id:string} | {kind:'subplane', subplane:Subplane, id:string}>} */
33
33
  const stack = [];
34
34
  const planes = new Map();
35
35
  const subplanes = new Map();
@@ -58,7 +58,8 @@ export function createComponentContext() {
58
58
 
59
59
  const findPlane = () => {
60
60
  for (let i = stack.length - 1; i >= 0; i--) {
61
- if (stack[i].kind === "plane") return stack[i].plane;
61
+ const entry = stack[i];
62
+ if (entry.kind === "plane") return entry.plane;
62
63
  }
63
64
  return null;
64
65
  };
@@ -89,9 +90,11 @@ export function createComponentContext() {
89
90
  planes.set(id, plane);
90
91
  stack.push({ kind: "plane", plane, id });
91
92
  } else {
92
- const parentPlane = findPlane();
93
+ // findPlane is non-null here because the first stack entry
94
+ // is always a plane (openContainer with empty stack pushes one).
95
+ const parentPlane = /** @type {Plane} */ (findPlane() ?? ensureFloatingPlane());
93
96
  const sub = new Subplane({ id, title, kind });
94
- if (parentPlane?.color) sub.color = subplaneColor(parentPlane.color);
97
+ if (parentPlane.color) sub.color = subplaneColor(parentPlane.color);
95
98
  parentPlane.addSubplane(sub);
96
99
  subplanes.set(id, sub);
97
100
  stack.push({ kind: "subplane", subplane: sub, id });
@@ -52,28 +52,41 @@ import { stripComment, ALWAYS_SKIP } from "./utils.mjs";
52
52
  * @param {Record<string, any>} args.ctx Mutable context object. Plugins
53
53
  * attach state here; the engine never
54
54
  * reads it directly.
55
+ * @param {(info: {line: string, index: number}) => void} [args.onUnknownLine]
56
+ * Optional callback invoked for every non-skip, non-empty line that
57
+ * no plugin consumed. Useful for `strict`/`diagnostics` modes; the
58
+ * default behaviour (silent ignore) is preserved when omitted.
55
59
  * @returns {object} Whatever `ctx.result` exposes —
56
60
  * typically a `Diagram` /
57
61
  * `SequenceDiagram` instance.
58
62
  * @public
59
63
  */
60
- export function runEngine({ lines, plugins, ctx }) {
64
+ export function runEngine({ lines, plugins, ctx, onUnknownLine }) {
61
65
  /** @type {PluginBlock | null} */
62
66
  let block = null;
67
+ let index = 0;
63
68
  for (const raw of lines) {
64
69
  const line = stripComment(raw).trim();
65
70
 
66
71
  if (block) {
67
72
  if (block.tryEnd(line, ctx)) {
68
73
  block = null;
74
+ index++;
69
75
  continue;
70
76
  }
71
77
  block.onLine(line, ctx);
78
+ index++;
72
79
  continue;
73
80
  }
74
81
 
75
- if (!line) continue;
76
- if (ALWAYS_SKIP.some((re) => re.test(line))) continue;
82
+ if (!line) {
83
+ index++;
84
+ continue;
85
+ }
86
+ if (ALWAYS_SKIP.some((re) => re.test(line))) {
87
+ index++;
88
+ continue;
89
+ }
77
90
 
78
91
  let consumed = false;
79
92
  for (const p of plugins) {
@@ -90,8 +103,10 @@ export function runEngine({ lines, plugins, ctx }) {
90
103
  break;
91
104
  }
92
105
  }
93
- // Unknown lines are silently ignored — same tolerance as before.
94
- void consumed;
106
+ if (!consumed && typeof onUnknownLine === "function") {
107
+ onUnknownLine({ line, index });
108
+ }
109
+ index++;
95
110
  }
96
111
  ctx.finalize?.();
97
112
  return ctx.result;
@@ -95,6 +95,21 @@ export const DEFAULT_SEQUENCE_PLUGINS = [
95
95
  messagePlugin,
96
96
  ];
97
97
 
98
+ /**
99
+ * Default upper bounds for `parsePlantUml`. Callers can override any
100
+ * of these via the `limits` option. The defaults are generous (10 MiB
101
+ * source, 100k lines, 10k boxes/edges) so legitimate large diagrams
102
+ * still parse, but malicious or runaway inputs fail fast instead of
103
+ * exhausting memory.
104
+ * @public
105
+ */
106
+ export const DEFAULT_PARSE_LIMITS = Object.freeze({
107
+ maxInputBytes: 10 * 1024 * 1024,
108
+ maxLines: 100_000,
109
+ maxNodes: 10_000,
110
+ maxEdges: 10_000,
111
+ });
112
+
98
113
  /**
99
114
  * Parse a PlantUML source string into the input-agnostic diagram model.
100
115
  * The parser auto-detects sequence vs. component syntax via the
@@ -105,6 +120,14 @@ export const DEFAULT_SEQUENCE_PLUGINS = [
105
120
  * @param {{component?: any[], sequence?: any[]}} [opts.plugins]
106
121
  * Override the default plugin lists. Useful for adding support for
107
122
  * unsupported PlantUML constructs without forking the library.
123
+ * @param {Partial<typeof DEFAULT_PARSE_LIMITS>} [opts.limits]
124
+ * Override one or more resource limits. Anything omitted keeps the
125
+ * default. Pass `null`/`Infinity` to disable a particular limit.
126
+ * @param {"silent"|"warn"|"strict"} [opts.unknownLines]
127
+ * How to handle PlantUML lines that no plugin consumes. `silent`
128
+ * (the default, preserves existing behaviour) drops them. `warn`
129
+ * emits a `console.warn` per line. `strict` throws a `SyntaxError`
130
+ * listing every unknown line.
108
131
  * @returns {import("../model/diagram.mjs").Diagram
109
132
  * | import("../model/diagram.mjs").SequenceDiagram}
110
133
  * @public
@@ -112,24 +135,99 @@ export const DEFAULT_SEQUENCE_PLUGINS = [
112
135
  export function parsePlantUml(text, opts = {}) {
113
136
  const componentPlugins = opts.plugins?.component ?? DEFAULT_COMPONENT_PLUGINS;
114
137
  const sequencePlugins = opts.plugins?.sequence ?? DEFAULT_SEQUENCE_PLUGINS;
138
+ const limits = { ...DEFAULT_PARSE_LIMITS, ...(opts.limits || {}) };
139
+ const unknownMode = opts.unknownLines ?? "silent";
140
+
141
+ if (typeof text !== "string") {
142
+ throw new TypeError("parsePlantUml: `text` must be a string");
143
+ }
144
+ const byteLen = Buffer.byteLength(text, "utf8");
145
+ if (Number.isFinite(limits.maxInputBytes) && byteLen > limits.maxInputBytes) {
146
+ throw new RangeError(
147
+ `parsePlantUml: input is ${byteLen} bytes, exceeds maxInputBytes=${limits.maxInputBytes}`,
148
+ );
149
+ }
150
+ const lines = text.split(/\r?\n/);
151
+ if (Number.isFinite(limits.maxLines) && lines.length > limits.maxLines) {
152
+ throw new RangeError(
153
+ `parsePlantUml: input has ${lines.length} lines, exceeds maxLines=${limits.maxLines}`,
154
+ );
155
+ }
156
+
157
+ /** @type {Array<{line:string,index:number}>} */
158
+ const unknown = [];
159
+ const onUnknownLine =
160
+ unknownMode === "silent"
161
+ ? undefined
162
+ : (/** @type {{line:string,index:number}} */ info) => {
163
+ unknown.push(info);
164
+ if (unknownMode === "warn") {
165
+ console.warn(`parsePlantUml: unknown line ${info.index + 1}: ${info.line}`);
166
+ }
167
+ };
115
168
 
169
+ let diagram;
116
170
  if (looksLikeSequence(text)) {
117
- return /** @type {import("../model/diagram.mjs").SequenceDiagram} */ (
171
+ diagram = /** @type {import("../model/diagram.mjs").SequenceDiagram} */ (
118
172
  runEngine({
119
- lines: text.split(/\r?\n/),
173
+ lines,
120
174
  plugins: sequencePlugins,
121
175
  ctx: createSequenceContext(),
176
+ onUnknownLine,
122
177
  })
123
178
  );
179
+ } else {
180
+ diagram = /** @type {import("../model/diagram.mjs").Diagram} */ (
181
+ runEngine({
182
+ lines: explodeBraces(lines),
183
+ plugins: componentPlugins,
184
+ ctx: createComponentContext(),
185
+ onUnknownLine,
186
+ })
187
+ );
188
+ }
189
+ if (unknownMode === "strict" && unknown.length) {
190
+ const detail = unknown
191
+ .slice(0, 10)
192
+ .map((u) => ` line ${u.index + 1}: ${u.line}`)
193
+ .join("\n");
194
+ const more = unknown.length > 10 ? `\n ...and ${unknown.length - 10} more` : "";
195
+ throw new SyntaxError(`parsePlantUml: ${unknown.length} unknown line(s):\n${detail}${more}`);
124
196
  }
197
+ enforceModelLimits(diagram, limits);
198
+ return diagram;
199
+ }
125
200
 
126
- return /** @type {import("../model/diagram.mjs").Diagram} */ (
127
- runEngine({
128
- lines: explodeBraces(text.split(/\r?\n/)),
129
- plugins: componentPlugins,
130
- ctx: createComponentContext(),
131
- })
132
- );
201
+ /**
202
+ * Walk the parsed model and reject diagrams that exceed `limits`.
203
+ * Counts boxes (incl. notes) across all planes/subplanes and the
204
+ * connection list. Sequence diagrams are bounded by participant +
205
+ * message + note counts.
206
+ * @param {any} diagram Parsed model.
207
+ * @param {{maxNodes:number, maxEdges:number}} limits Effective limits.
208
+ */
209
+ function enforceModelLimits(diagram, limits) {
210
+ let nodes = 0;
211
+ let edges = 0;
212
+ if (Array.isArray(diagram?.planes)) {
213
+ for (const plane of diagram.planes) {
214
+ nodes += plane.allBoxes?.length ?? plane.boxes?.length ?? 0;
215
+ }
216
+ edges = diagram.connections?.length ?? 0;
217
+ } else {
218
+ nodes = (diagram?.participants?.length ?? 0) + (diagram?.notes?.length ?? 0);
219
+ edges = diagram?.messages?.length ?? 0;
220
+ }
221
+ if (Number.isFinite(limits.maxNodes) && nodes > limits.maxNodes) {
222
+ throw new RangeError(
223
+ `parsePlantUml: diagram has ${nodes} nodes, exceeds maxNodes=${limits.maxNodes}`,
224
+ );
225
+ }
226
+ if (Number.isFinite(limits.maxEdges) && edges > limits.maxEdges) {
227
+ throw new RangeError(
228
+ `parsePlantUml: diagram has ${edges} edges, exceeds maxEdges=${limits.maxEdges}`,
229
+ );
230
+ }
133
231
  }
134
232
 
135
233
  // Sequence-only keywords trigger the sequence pipeline. `actor` and
@@ -4,11 +4,26 @@
4
4
  // decoded by `classifyArrow()`; to support a new arrow operator just
5
5
  // extend that classifier.
6
6
 
7
- import { classifyArrow, unescapeLabel } from "../../utils.mjs";
7
+ import { classifyArrow, slug, unescapeLabel } from "../../utils.mjs";
8
8
 
9
9
  const CONNECTION_LINE =
10
10
  /^(\S+)\s+([-.*o<|>]+(?:up|down|left|right|UP|DOWN|LEFT|RIGHT)?[-.*o<|>]*)\s+(\S+)(?:\s*:\s*(.+))?$/;
11
11
 
12
+ /**
13
+ * Normalise a connection endpoint so that bracket / paren shorthands
14
+ * (`[Foo]`, `(Use case)`) and quoted labels resolve to the same
15
+ * identifier the corresponding shape declaration uses.
16
+ * @param {string} raw Raw token captured by the connection regex.
17
+ * @returns {string} Identifier suitable for the box-id lookup table.
18
+ */
19
+ function normaliseEndpoint(raw) {
20
+ let s = raw.trim();
21
+ if (s.startsWith("[") && s.endsWith("]")) return slug(s.slice(1, -1));
22
+ if (s.startsWith("(") && s.endsWith(")")) return slug(s.slice(1, -1));
23
+ if (s.startsWith('"') && s.endsWith('"')) return slug(s.slice(1, -1));
24
+ return s;
25
+ }
26
+
12
27
  /**
13
28
  * Generic component-style connection: `A op B [: label]`. All arrow
14
29
  * flavours are decoded by `classifyArrow()` — extend that to support
@@ -20,9 +35,11 @@ export const connectionPlugin = {
20
35
  tryLine(line, ctx) {
21
36
  const m = line.match(CONNECTION_LINE);
22
37
  if (!m) return false;
23
- const [, fromId, op, toId, label] = m;
38
+ const [, rawFrom, op, rawTo, label] = m;
24
39
  const arrow = classifyArrow(op);
25
40
  if (!arrow) return false;
41
+ const fromId = normaliseEndpoint(rawFrom);
42
+ const toId = normaliseEndpoint(rawTo);
26
43
  ctx.queueConnection({
27
44
  fromId,
28
45
  toId,
@@ -23,6 +23,7 @@ export function createSequenceContext() {
23
23
  const diagram = new SequenceDiagram();
24
24
  let messageCounter = 0;
25
25
  let noteCounter = 0;
26
+ let timelineCounter = 0;
26
27
 
27
28
  const ctx = {
28
29
  get result() {
@@ -66,7 +67,8 @@ export function createSequenceContext() {
66
67
  stereotype = "",
67
68
  },
68
69
  ) {
69
- if (diagram.participantById(id)) return diagram.participantById(id);
70
+ const existing = diagram.participantById(id);
71
+ if (existing) return existing;
70
72
  const p = new Participant({ id, title, shape, stereotype });
71
73
  diagram.addParticipant(p);
72
74
  return p;
@@ -86,14 +88,18 @@ export function createSequenceContext() {
86
88
  * @param {any} spec Plugin-built message record (without id).
87
89
  */
88
90
  addMessage(/** @type {any} */ spec) {
89
- diagram.addMessage(new Message({ id: ctx.nextMessageId(), ...spec }));
91
+ const msg = new Message({ id: ctx.nextMessageId(), ...spec });
92
+ msg.seq = timelineCounter++;
93
+ diagram.addMessage(msg);
90
94
  },
91
95
  /**
92
96
  * Append a new note to the diagram (id is auto-assigned).
93
97
  * @param {any} spec Plugin-built note record (without id).
94
98
  */
95
99
  addNote(/** @type {any} */ spec) {
96
- diagram.addNote(new SequenceNote({ id: ctx.nextNoteId(), ...spec }));
100
+ const note = new SequenceNote({ id: ctx.nextNoteId(), ...spec });
101
+ note.seq = timelineCounter++;
102
+ diagram.addNote(note);
97
103
  },
98
104
  };
99
105
  return ctx;
@@ -44,10 +44,23 @@ export const ALWAYS_SKIP = [
44
44
  * @public
45
45
  */
46
46
  export function stripComment(line) {
47
- // PlantUML: ' starts a line comment except inside a string.
48
- const idx = line.indexOf("'");
49
- if (idx === 0) return "";
50
- if (idx > 0 && /\s/.test(line[idx - 1])) return line.slice(0, idx);
47
+ // PlantUML: `'` starts a line comment, but inside a `"..."` string
48
+ // literal the apostrophe is just a regular character. Walk the line
49
+ // tracking quote state so labels like `"Bob 's service"` survive.
50
+ let inQuotes = false;
51
+ for (let i = 0; i < line.length; i++) {
52
+ const ch = line[i];
53
+ if (ch === '"') {
54
+ inQuotes = !inQuotes;
55
+ continue;
56
+ }
57
+ if (inQuotes) continue;
58
+ if (ch === "'") {
59
+ if (i === 0) return "";
60
+ const prev = line[i - 1];
61
+ if (/\s/.test(prev)) return line.slice(0, i);
62
+ }
63
+ }
51
64
  return line;
52
65
  }
53
66
 
@@ -64,17 +77,25 @@ export function stripQuotes(s) {
64
77
  }
65
78
 
66
79
  /**
67
- * Convert any string to an identifier-safe slug (`[a-z0-9_]+`).
80
+ * Convert any string to an identifier-safe slug. Preserves Unicode
81
+ * letters and digits (e.g. `ümlaut`, `日本`) while collapsing every
82
+ * other character to `_`. Falls back to a hashed identifier if the
83
+ * input has no letters/digits at all so that connections never lose
84
+ * their endpoint id.
68
85
  *
69
86
  * @param {string} s Free-form text to sluggify.
70
87
  * @returns {string} Lower-case, underscore-separated identifier.
71
88
  * @public
72
89
  */
73
90
  export function slug(s) {
74
- return String(s)
75
- .toLowerCase()
76
- .replace(/[^a-z0-9]+/g, "_")
77
- .replace(/^_+|_+$/g, "");
91
+ const raw = String(s).toLowerCase();
92
+ const cleaned = raw.replace(/[^\p{L}\p{N}]+/gu, "_").replace(/^_+|_+$/g, "");
93
+ if (cleaned) return cleaned;
94
+ // No letters/digits at all – derive a stable fallback so that
95
+ // `[***]` and similar still produce a usable id.
96
+ let h = 0;
97
+ for (let i = 0; i < raw.length; i++) h = (h * 31 + raw.charCodeAt(i)) | 0;
98
+ return `id_${(h >>> 0).toString(36)}`;
78
99
  }
79
100
 
80
101
  /**
@@ -8,7 +8,7 @@
8
8
  // no extra runtime dependencies; the PNG path
9
9
  // (`./png.mjs`) needs `@resvg/resvg-js` to be installed.
10
10
 
11
- import { excalidrawToSvg } from "./svg.mjs";
11
+ import { excalidrawToSvg, escapeAttr } from "./svg.mjs";
12
12
 
13
13
  export const DEFAULT_CANVAS_WIDTH = 1200;
14
14
  export const MIN_CANVAS_WIDTH = 16;
@@ -40,7 +40,8 @@ export function excalidrawJsonToCanvasSvg(doc, opts = {}) {
40
40
 
41
41
  const inner = excalidrawToSvg(doc, { padding });
42
42
  const innerVb = parseViewBox(inner);
43
- if (!innerVb) return blankCanvas(width, height, background);
43
+ const safeBackground = escapeAttr(background);
44
+ if (!innerVb) return blankCanvas(width, height, safeBackground);
44
45
 
45
46
  const scale = Math.min(width / innerVb.w, height / innerVb.h);
46
47
  const drawnW = innerVb.w * scale;
@@ -54,7 +55,7 @@ export function excalidrawJsonToCanvasSvg(doc, opts = {}) {
54
55
  `<svg xmlns="http://www.w3.org/2000/svg" ` +
55
56
  `width="${width}" height="${height}" ` +
56
57
  `viewBox="0 0 ${width} ${height}">`,
57
- `<rect width="${width}" height="${height}" fill="${background}"/>`,
58
+ `<rect width="${width}" height="${height}" fill="${safeBackground}"/>`,
58
59
  `<g transform="translate(${offsetX} ${offsetY}) scale(${scale}) ` +
59
60
  `translate(${-innerVb.x} ${-innerVb.y})">`,
60
61
  innerBody,
@@ -351,21 +351,26 @@ function colorOrNone(c) {
351
351
  return c;
352
352
  }
353
353
 
354
- /** @internal */
355
354
  /**
356
355
  * Escape a string for safe interpolation into an SVG attribute value.
356
+ * Escapes `&`, `"`, `<` and `>` so attacker-controlled input cannot
357
+ * break out of the surrounding `"..."` and inject extra attributes
358
+ * or markup.
357
359
  * @param {string} s Raw string.
358
360
  * @returns {string} Escaped string.
359
361
  */
360
- function escapeAttr(s) {
361
- return String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
362
+ export function escapeAttr(s) {
363
+ return String(s)
364
+ .replace(/&/g, "&amp;")
365
+ .replace(/"/g, "&quot;")
366
+ .replace(/</g, "&lt;")
367
+ .replace(/>/g, "&gt;");
362
368
  }
363
- /** @internal */
364
369
  /**
365
370
  * Escape a string for safe interpolation into SVG text content.
366
371
  * @param {string} s Raw string.
367
372
  * @returns {string} Escaped string.
368
373
  */
369
- function escapeText(s) {
374
+ export function escapeText(s) {
370
375
  return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
371
376
  }