@bpmnkit/core 1.6.1 → 1.8.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 (78) hide show
  1. package/AGENTS.md +19 -0
  2. package/README.md +2 -0
  3. package/agent-cards/bpmn.md +86 -0
  4. package/agent-cards/dmn.md +105 -0
  5. package/agent-cards/form.md +72 -0
  6. package/builder-reference.md +211 -0
  7. package/dist/bpmn/auto-layout.js +34 -5
  8. package/dist/bpmn/bpmn-builder.d.ts +127 -5
  9. package/dist/bpmn/bpmn-builder.js +270 -40
  10. package/dist/bpmn/bpmn-model.d.ts +2 -0
  11. package/dist/bpmn/bpmn-parser.js +8 -0
  12. package/dist/bpmn/bpmn-serializer.js +1 -1
  13. package/dist/bpmn/builder-coverage.js +4 -12
  14. package/dist/bpmn/camunda7/export.d.ts +25 -0
  15. package/dist/bpmn/camunda7/export.js +218 -0
  16. package/dist/bpmn/camunda7/migrate.d.ts +4 -1
  17. package/dist/bpmn/camunda7/migrate.js +4 -4
  18. package/dist/bpmn/compact.d.ts +21 -0
  19. package/dist/bpmn/compact.js +86 -1
  20. package/dist/bpmn/full-operations.js +338 -3
  21. package/dist/bpmn/index.d.ts +2 -0
  22. package/dist/bpmn/index.js +2 -0
  23. package/dist/bpmn/operations.d.ts +42 -1
  24. package/dist/bpmn/operations.js +12 -2
  25. package/dist/bpmn/optimize/deploy.js +14 -0
  26. package/dist/bpmn/optimize/index.d.ts +2 -0
  27. package/dist/bpmn/optimize/index.js +5 -0
  28. package/dist/bpmn/optimize/types.d.ts +7 -0
  29. package/dist/bpmn/stable-ids.d.ts +15 -0
  30. package/dist/bpmn/stable-ids.js +26 -0
  31. package/dist/bpmn/strip-camunda8.d.ts +22 -0
  32. package/dist/bpmn/strip-camunda8.js +55 -0
  33. package/dist/bpmn/svg.js +5 -6
  34. package/dist/bpmn/utils.js +151 -1
  35. package/dist/bpmn/zeebe-extensions.d.ts +59 -2
  36. package/dist/bpmn/zeebe-extensions.js +89 -1
  37. package/dist/check-finding.d.ts +19 -0
  38. package/dist/check-finding.js +5 -0
  39. package/dist/connectors/apply-element.d.ts +7 -3
  40. package/dist/connectors/apply-element.js +115 -4
  41. package/dist/connectors/apply-many.d.ts +5 -1
  42. package/dist/connectors/apply-many.js +5 -2
  43. package/dist/connectors/apply.d.ts +24 -3
  44. package/dist/connectors/apply.js +103 -3
  45. package/dist/connectors/catalog.js +5 -0
  46. package/dist/connectors/index.d.ts +1 -1
  47. package/dist/connectors/template-types.d.ts +30 -0
  48. package/dist/connectors/validate.js +33 -0
  49. package/dist/dmn/compact.js +14 -5
  50. package/dist/dmn/dmn-builder.js +3 -3
  51. package/dist/dmn/drd-builder.d.ts +53 -0
  52. package/dist/dmn/drd-builder.js +100 -0
  53. package/dist/dmn/index.d.ts +35 -0
  54. package/dist/dmn/index.js +36 -0
  55. package/dist/dmn/lint.d.ts +19 -0
  56. package/dist/dmn/lint.js +414 -0
  57. package/dist/form/form-builder.d.ts +9 -1
  58. package/dist/form/form-builder.js +34 -1
  59. package/dist/form/form-model.d.ts +7 -0
  60. package/dist/form/form-parser.js +22 -0
  61. package/dist/form/form-serializer.js +10 -0
  62. package/dist/form/index.d.ts +11 -2
  63. package/dist/form/index.js +10 -1
  64. package/dist/form/lint.d.ts +19 -0
  65. package/dist/form/lint.js +356 -0
  66. package/dist/index.d.ts +19 -5
  67. package/dist/index.js +12 -2
  68. package/dist/layout/annotations.d.ts +3 -1
  69. package/dist/layout/annotations.js +72 -14
  70. package/dist/layout/grid/edge-labels.d.ts +7 -1
  71. package/dist/layout/grid/edge-labels.js +62 -1
  72. package/dist/layout/semantic/index.js +78 -8
  73. package/dist/layout/semantic/place.d.ts +19 -4
  74. package/dist/layout/semantic/place.js +245 -29
  75. package/dist/layout/semantic/route.js +60 -12
  76. package/dist/layout/types.d.ts +2 -1
  77. package/llms.txt +9 -0
  78. package/package.json +6 -1
@@ -1,8 +1,23 @@
1
- import { ELEMENT_SIZES, LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH } from "../types.js";
1
+ import { ELEMENT_SIZES, LABEL_CHAR_WIDTH, LABEL_HEIGHT, LABEL_MIN_WIDTH, LABEL_VERTICAL_OFFSET, } from "../types.js";
2
2
  import { boundarySide } from "./bands.js";
3
- /** Geometry constants. Layout may add space beyond these; it never takes any back. */
4
- export const H_GAP = 100;
5
- export const V_GAP = 80;
3
+ /**
4
+ * Geometry constants. Layout may add space beyond these; it never takes any back.
5
+ * Hand-drawn diagrams keep about 50-60 px between neighbouring shapes; wider
6
+ * gaps only where a flow label or a long event label needs the room.
7
+ */
8
+ export const H_GAP = 60;
9
+ export const V_GAP = 60;
10
+ /**
11
+ * Gap beside a column holding an expanded container. The container's border,
12
+ * its title and the notes on its children crowd that gap, so it keeps more air.
13
+ */
14
+ export const CONTAINER_GAP = 100;
15
+ /** Clear space either side of a flow label inside a column gap. */
16
+ const LABEL_MARGIN = 10;
17
+ /** Gap between an event or gateway and its external label (mirrors `index.ts`). */
18
+ const EXTERNAL_LABEL_OFFSET = 4;
19
+ const GRID_GAP_X = 40;
20
+ const GRID_GAP_Y = 20;
6
21
  export const COMPONENT_GAP = 80;
7
22
  export const LANE_PADDING = 40;
8
23
  export const BOUNDARY_SIZE = 36;
@@ -55,7 +70,13 @@ packLoose = false,
55
70
  */
56
71
  titled = new Set(),
57
72
  /** Shape of the `packLoose` grid, when the builder asked for one. */
58
- grid) {
73
+ grid,
74
+ /**
75
+ * For expanded containers with a flow inside: the distance from the
76
+ * container's top to its inner spine. The container is hung so that spine
77
+ * continues the row's line, and the flow runs straight through it.
78
+ */
79
+ axes = new Map()) {
59
80
  const bounds = new Map();
60
81
  const componentOf = new Map();
61
82
  for (let i = 0; i < graph.components.length; i++) {
@@ -69,15 +90,27 @@ grid) {
69
90
  const size = sizes.get(node.id) ?? DEFAULT_SIZE;
70
91
  colWidth.set(rank, Math.max(colWidth.get(rank) ?? 0, size.width));
71
92
  }
93
+ const ranks = [...colWidth.keys()].sort((a, b) => a - b);
94
+ const gaps = columnGaps(graph, sizes, colWidth, ranks);
72
95
  const colX = new Map();
73
96
  const gutterX = new Map();
74
97
  let x = 0;
75
- for (const rank of [...colWidth.keys()].sort((a, b) => a - b)) {
98
+ for (const [i, rank] of ranks.entries()) {
99
+ const gap = gaps.get(rank) ?? H_GAP;
100
+ if (i > 0)
101
+ x += gap;
76
102
  colX.set(rank, x);
77
- gutterX.set(rank, x - H_GAP / 2);
78
- x += (colWidth.get(rank) ?? 0) + H_GAP;
103
+ gutterX.set(rank, x - gap / 2);
104
+ x += colWidth.get(rank) ?? 0;
79
105
  }
80
- // ── Rows: one per band, laid out per component then stacked ──
106
+ const xOf = (id) => {
107
+ const size = sizes.get(id) ?? DEFAULT_SIZE;
108
+ const rank = graph.ranks.get(id) ?? 0;
109
+ const cw = colWidth.get(rank) ?? size.width;
110
+ const left = (colX.get(rank) ?? 0) + (cw - size.width) / 2;
111
+ return { left, right: left + size.width, width: size.width };
112
+ };
113
+ // ── Rows: one line per band, laid out per component then stacked ──
81
114
  const loose = packLoose ? looseNodes(graph) : [];
82
115
  const looseSet = new Set(loose);
83
116
  let cursorY = 0;
@@ -91,38 +124,214 @@ grid) {
91
124
  cursorY = placeGrid(graph, loose, sizes, cursorY, bounds, grid);
92
125
  continue;
93
126
  }
94
- const rowHeight = new Map();
127
+ const lines = bandLines(graph, bandLayout, members, sizes, xOf, axes, titled);
128
+ let top = Number.POSITIVE_INFINITY;
129
+ let bottom = Number.NEGATIVE_INFINITY;
95
130
  for (const id of members) {
96
- const band = bandLayout.bands.get(id) ?? 0;
97
- const size = sizes.get(id) ?? DEFAULT_SIZE;
98
- rowHeight.set(band, Math.max(rowHeight.get(band) ?? 0, size.height));
99
- }
100
- const rowY = new Map();
101
- let y = cursorY;
102
- for (const band of [...rowHeight.keys()].sort((a, b) => a - b)) {
103
- rowY.set(band, y);
104
- y += (rowHeight.get(band) ?? 0) + V_GAP;
131
+ const line = lines.line.get(bandLayout.bands.get(id) ?? 0) ?? 0;
132
+ const extent = lines.extent.get(id);
133
+ if (!extent)
134
+ continue;
135
+ top = Math.min(top, line - extent.above);
136
+ bottom = Math.max(bottom, line + extent.below);
105
137
  }
138
+ const dy = cursorY - top;
106
139
  for (const id of members) {
107
140
  const size = sizes.get(id) ?? DEFAULT_SIZE;
108
- const rank = graph.ranks.get(id) ?? 0;
109
- const band = bandLayout.bands.get(id) ?? 0;
110
- const cw = colWidth.get(rank) ?? size.width;
111
- const rh = rowHeight.get(band) ?? size.height;
141
+ const line = lines.line.get(bandLayout.bands.get(id) ?? 0) ?? 0;
142
+ const { left } = xOf(id);
112
143
  bounds.set(id, {
113
- x: (colX.get(rank) ?? 0) + (cw - size.width) / 2,
114
- y: (rowY.get(band) ?? 0) + (rh - size.height) / 2,
144
+ x: left,
145
+ y: line + dy - centreOffset(id, size, axes),
115
146
  width: size.width,
116
147
  height: size.height,
117
148
  });
118
149
  }
119
- cursorY = y - V_GAP + COMPONENT_GAP;
150
+ cursorY = bottom + dy + COMPONENT_GAP;
120
151
  }
121
152
  separateSameCell(graph, bandLayout, bounds);
122
153
  const lanes = laneSet ? applyLanes(graph, laneSet, bounds) : [];
123
154
  dockBoundaryEvents(graph, bounds, titled);
124
155
  return { bounds, lanes, gutterX };
125
156
  }
157
+ /**
158
+ * The gap in front of each rank. At least {@link H_GAP}; wider where a flow
159
+ * label sits between two neighbouring columns, or where events' and gateways'
160
+ * labels, centred below shapes narrower than themselves, would meet.
161
+ */
162
+ function columnGaps(graph, sizes, colWidth, ranks) {
163
+ const rankOf = (id) => {
164
+ const el = graph.byId.get(id);
165
+ const host = el?.type === "boundaryEvent" ? el.attachedToRef : id;
166
+ return graph.ranks.get(host) ?? 0;
167
+ };
168
+ const position = new Map(ranks.map((rank, i) => [rank, i]));
169
+ const tall = new Set();
170
+ for (const node of graph.nodes) {
171
+ if ((sizes.get(node.id) ?? DEFAULT_SIZE).height > DEFAULT_SIZE.height) {
172
+ tall.add(graph.ranks.get(node.id) ?? 0);
173
+ }
174
+ }
175
+ const overhang = new Map();
176
+ for (const node of graph.nodes) {
177
+ if (!node.name)
178
+ continue;
179
+ const width = externalLabelWidth(node.type, node.name);
180
+ if (width === undefined)
181
+ continue;
182
+ const rank = graph.ranks.get(node.id) ?? 0;
183
+ const cw = colWidth.get(rank) ?? (sizes.get(node.id) ?? DEFAULT_SIZE).width;
184
+ overhang.set(rank, Math.max(overhang.get(rank) ?? 0, (width - cw) / 2));
185
+ }
186
+ const gaps = new Map();
187
+ for (const [i, rank] of ranks.entries()) {
188
+ if (i === 0)
189
+ continue;
190
+ const previous = ranks[i - 1];
191
+ const labels = Math.max(0, overhang.get(previous) ?? 0) + Math.max(0, overhang.get(rank) ?? 0);
192
+ const base = tall.has(rank) || tall.has(previous) ? CONTAINER_GAP : H_GAP;
193
+ gaps.set(rank, Math.max(base, labels + 2 * EXTERNAL_LABEL_OFFSET + LABEL_MARGIN));
194
+ }
195
+ for (const flows of graph.outgoing.values()) {
196
+ for (const flow of flows) {
197
+ if (!flow.name || graph.backEdges.has(flow.id))
198
+ continue;
199
+ const target = rankOf(flow.targetRef);
200
+ const at = position.get(target);
201
+ if (at === undefined || at === 0)
202
+ continue;
203
+ // Only a flow between neighbouring columns has nowhere else to put its label.
204
+ if (position.get(rankOf(flow.sourceRef)) !== at - 1)
205
+ continue;
206
+ const need = Math.max(flow.name.length * LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH) + 2 * LABEL_MARGIN;
207
+ gaps.set(target, Math.max(gaps.get(target) ?? H_GAP, need));
208
+ }
209
+ }
210
+ return gaps;
211
+ }
212
+ /** How far a node's centre line sits below its top. */
213
+ function centreOffset(id, size, axes) {
214
+ if (size.height <= DEFAULT_SIZE.height)
215
+ return size.height / 2;
216
+ // A tall container carries its inner spine on the row's line; one without an
217
+ // inner flow (a tool grid) hangs from the task line instead.
218
+ return axes.get(id) ?? DEFAULT_SIZE.height / 2;
219
+ }
220
+ /**
221
+ * Space a node needs above and below its band's line: its shape, the label
222
+ * below an event or gateway, and the boundary events docked on its borders
223
+ * together with their labels.
224
+ */
225
+ function extentOf(graph, id, size, axes, titled) {
226
+ const offset = centreOffset(id, size, axes);
227
+ let above = offset;
228
+ let below = size.height - offset;
229
+ const el = graph.byId.get(id);
230
+ if (el?.name && externalLabelWidth(el.type, el.name) !== undefined) {
231
+ below = Math.max(below, size.height / 2 + EXTERNAL_LABEL_OFFSET + LABEL_HEIGHT);
232
+ }
233
+ for (const event of graph.attachers.get(id) ?? []) {
234
+ const reach = BOUNDARY_SIZE / 2 + (event.name ? EXTERNAL_LABEL_OFFSET + LABEL_HEIGHT : 0);
235
+ if (boundarySide(event, titled.has(id)) === -1)
236
+ above = Math.max(above, offset + reach);
237
+ else
238
+ below = Math.max(below, size.height - offset + reach);
239
+ }
240
+ return { above, below };
241
+ }
242
+ /**
243
+ * The y of each band's line, relative to the spine at 0.
244
+ *
245
+ * Bands keep their order, but a band only clears what it actually sits under
246
+ * or over: the shapes above it in its own columns, and those its connecting
247
+ * flows run past. A tall sub-process therefore pushes down only the branches
248
+ * beneath it, not every branch in the diagram.
249
+ */
250
+ function bandLines(graph, bandLayout, members, sizes, xOf, axes, titled) {
251
+ const extent = new Map();
252
+ const byBand = new Map();
253
+ for (const id of members) {
254
+ extent.set(id, extentOf(graph, id, sizes.get(id) ?? DEFAULT_SIZE, axes, titled));
255
+ const band = bandLayout.bands.get(id) ?? 0;
256
+ const list = byBand.get(band);
257
+ if (list)
258
+ list.push(id);
259
+ else
260
+ byBand.set(band, [id]);
261
+ }
262
+ const line = new Map();
263
+ /** Placed boxes: x-range and how far they reach above / below their line. */
264
+ const placed = [];
265
+ const place = (band, y) => {
266
+ line.set(band, y);
267
+ for (const id of byBand.get(band) ?? []) {
268
+ const { left, right } = xOf(id);
269
+ const e = extent.get(id);
270
+ placed.push({ left, right, top: y - e.above, bottom: y + e.below });
271
+ }
272
+ };
273
+ /** Centre x of every node a band's members connect to, so the band clears its own flows. */
274
+ const span = (band) => {
275
+ let left = Number.POSITIVE_INFINITY;
276
+ let right = Number.NEGATIVE_INFINITY;
277
+ const memberSet = new Set(byBand.get(band) ?? []);
278
+ const take = (id) => {
279
+ const el = graph.byId.get(id);
280
+ const host = el?.type === "boundaryEvent" ? el.attachedToRef : id;
281
+ if (!graph.byId.has(host))
282
+ return;
283
+ const b = xOf(host);
284
+ const mid = b.left + b.width / 2;
285
+ left = Math.min(left, memberSet.has(host) ? b.left : mid);
286
+ right = Math.max(right, memberSet.has(host) ? b.right : mid);
287
+ };
288
+ for (const id of memberSet) {
289
+ take(id);
290
+ for (const f of graph.outgoing.get(id) ?? [])
291
+ if (!graph.backEdges.has(f.id))
292
+ take(f.targetRef);
293
+ for (const f of graph.incoming.get(id) ?? [])
294
+ if (!graph.backEdges.has(f.id))
295
+ take(f.sourceRef);
296
+ }
297
+ return { left, right };
298
+ };
299
+ const xOverlap = (a, b) => a.left < b.right && b.left < a.right;
300
+ const bands = [...byBand.keys()];
301
+ if (byBand.has(0))
302
+ place(0, 0);
303
+ const below = bands.filter((b) => b > 0).sort((a, b) => a - b);
304
+ const above = bands.filter((b) => b < 0).sort((a, b) => b - a);
305
+ for (const [list, dir] of [
306
+ [below, 1],
307
+ [above, -1],
308
+ ]) {
309
+ let previous = 0;
310
+ for (const band of list) {
311
+ const wide = span(band);
312
+ let y = previous + dir;
313
+ for (const box of placed) {
314
+ if (xOverlap(box, wide)) {
315
+ y = dir === 1 ? Math.max(y, box.bottom + V_GAP) : Math.min(y, box.top - V_GAP);
316
+ }
317
+ for (const id of byBand.get(band) ?? []) {
318
+ const b = xOf(id);
319
+ const e = extent.get(id);
320
+ const reach = { left: b.left - H_GAP / 2, right: b.right + H_GAP / 2 };
321
+ if (!xOverlap(box, reach))
322
+ continue;
323
+ y =
324
+ dir === 1
325
+ ? Math.max(y, box.bottom + V_GAP + e.above)
326
+ : Math.min(y, box.top - V_GAP - e.below);
327
+ }
328
+ }
329
+ place(band, y);
330
+ previous = y;
331
+ }
332
+ }
333
+ return { line, extent };
334
+ }
126
335
  /**
127
336
  * Nodes with no incoming or outgoing flow, in declaration order — only when
128
337
  * there are at least two of them, since one has nothing to be packed with.
@@ -148,27 +357,34 @@ function placeGrid(graph, ids, sizes, top, bounds, hint) {
148
357
  const byColumn = hint?.fill === "column";
149
358
  let cellWidth = 0;
150
359
  let cellHeight = 0;
360
+ let labelled = false;
151
361
  for (const id of ids) {
152
362
  const size = sizes.get(id) ?? DEFAULT_SIZE;
153
363
  // An event's or gateway's label is centred below it and can be wider than the
154
364
  // shape; the cell holds it so neighbouring columns' labels never meet.
155
365
  const el = graph.byId.get(id);
156
366
  const label = el?.name ? externalLabelWidth(el.type, el.name) : undefined;
367
+ if (label !== undefined)
368
+ labelled = true;
157
369
  cellWidth = Math.max(cellWidth, size.width, label ?? 0);
158
370
  cellHeight = Math.max(cellHeight, size.height);
159
371
  }
372
+ // Loose nodes carry no flows, so the routing gutters are not needed between
373
+ // them; only a label below a cell needs vertical room.
374
+ const gapX = GRID_GAP_X;
375
+ const gapY = GRID_GAP_Y + (labelled ? LABEL_VERTICAL_OFFSET + LABEL_HEIGHT : 0);
160
376
  ids.forEach((id, i) => {
161
377
  const size = sizes.get(id) ?? DEFAULT_SIZE;
162
378
  const column = byColumn ? Math.floor(i / rows) : i % columns;
163
379
  const row = byColumn ? i % rows : Math.floor(i / columns);
164
380
  bounds.set(id, {
165
- x: column * (cellWidth + H_GAP) + (cellWidth - size.width) / 2,
166
- y: top + row * (cellHeight + V_GAP) + (cellHeight - size.height) / 2,
381
+ x: column * (cellWidth + gapX) + (cellWidth - size.width) / 2,
382
+ y: top + row * (cellHeight + gapY) + (cellHeight - size.height) / 2,
167
383
  width: size.width,
168
384
  height: size.height,
169
385
  });
170
386
  });
171
- return top + rows * (cellHeight + V_GAP) - V_GAP + COMPONENT_GAP;
387
+ return top + rows * (cellHeight + gapY) - gapY + COMPONENT_GAP;
172
388
  }
173
389
  /**
174
390
  * Two nodes can land in the same rank and band — a parallel split whose
@@ -98,7 +98,7 @@ export function routeFlows(graph, flows, bounds, bandLayout, gutterX) {
98
98
  : forwardCandidates(ctx, source, target, sourceRank, targetRank);
99
99
  const clear = pick(direct, ctx, flow.sourceRef, flow.targetRef);
100
100
  if (clear && clear.crossings <= CROSSING_TOLERANCE) {
101
- commit(ctx, routed, flow.id, clear.waypoints);
101
+ commit(ctx, routed, flow, clear.waypoints);
102
102
  continue;
103
103
  }
104
104
  pending.push({
@@ -119,12 +119,12 @@ export function routeFlows(graph, flows, bounds, bandLayout, gutterX) {
119
119
  const around = detour(ctx, item.source, item.target, item.sourceRank, item.targetRank, item.below, item.flow.sourceRef, item.flow.targetRef);
120
120
  // Going around costs bends and length, so it has to save more than one
121
121
  // crossing to be worth taking.
122
- const cost = crossingCount(around, ctx) + DETOUR_PENALTY;
122
+ const cost = crossingCount(around, ctx, item.flow.sourceRef, item.flow.targetRef) + DETOUR_PENALTY;
123
123
  const chosen = item.direct && item.direct.crossings <= cost ? item.direct.waypoints : around;
124
124
  const waypoints = blocked(ctx, chosen, item.flow.sourceRef, item.flow.targetRef)
125
125
  ? (searchRoute(ctx, item.flow, item.source, item.target) ?? chosen)
126
126
  : chosen;
127
- commit(ctx, routed, item.flow.id, waypoints);
127
+ commit(ctx, routed, item.flow, waypoints);
128
128
  }
129
129
  // Emit in declaration order, whichever pass produced the route.
130
130
  const edges = [];
@@ -180,13 +180,19 @@ function searchRoute(ctx, flow, source, target) {
180
180
  });
181
181
  }
182
182
  /** Record a chosen route so later edges can steer around it. */
183
- function commit(ctx, routed, id, waypoints) {
184
- routed.set(id, waypoints);
183
+ function commit(ctx, routed, flow, waypoints) {
184
+ routed.set(flow.id, waypoints);
185
185
  for (let i = 0; i + 1 < waypoints.length; i++) {
186
186
  const a = waypoints[i];
187
187
  const b = waypoints[i + 1];
188
- if (a && b)
189
- ctx.routed.insert(Math.min(a.x, b.x), Math.max(a.x, b.x), [a, b]);
188
+ if (a && b) {
189
+ ctx.routed.insert(Math.min(a.x, b.x), Math.max(a.x, b.x), [
190
+ a,
191
+ b,
192
+ flow.sourceRef,
193
+ flow.targetRef,
194
+ ]);
195
+ }
190
196
  }
191
197
  }
192
198
  function hostOf(graph, eventId) {
@@ -204,7 +210,7 @@ function pick(candidates, ctx, sourceId, targetId) {
204
210
  // the two endpoints are exempt from the obstacle check.
205
211
  if (blocked(ctx, candidate, sourceId, targetId))
206
212
  continue;
207
- const crossings = crossingCount(candidate, ctx);
213
+ const crossings = crossingCount(candidate, ctx, sourceId, targetId);
208
214
  if (crossings === 0)
209
215
  return { waypoints: candidate, crossings };
210
216
  if (!best || crossings < best.crossings)
@@ -217,22 +223,45 @@ function intersects(p, q, r, t) {
217
223
  const side = (o, a, b) => Math.sign((a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x));
218
224
  return side(p, q, r) !== side(p, q, t) && side(r, t, p) !== side(r, t, q);
219
225
  }
220
- /** How many already-routed edges a candidate would cut across. */
221
- function crossingCount(waypoints, ctx) {
226
+ /**
227
+ * How many already-routed edges a candidate would cut across, or run along:
228
+ * a stretch drawn on top of an unrelated flow reads as one line and hides
229
+ * where either goes. Flows sharing an endpoint may merge, as a join's do.
230
+ */
231
+ function crossingCount(waypoints, ctx, sourceId, targetId) {
222
232
  let count = 0;
223
233
  for (let i = 0; i + 1 < waypoints.length; i++) {
224
234
  const a = waypoints[i];
225
235
  const b = waypoints[i + 1];
226
236
  if (!a || !b)
227
237
  continue;
228
- ctx.routed.query(Math.min(a.x, b.x), Math.max(a.x, b.x), ([c, d]) => {
238
+ ctx.routed.query(Math.min(a.x, b.x), Math.max(a.x, b.x), ([c, d, from, to]) => {
229
239
  if (intersects(a, b, c, d))
230
240
  count++;
241
+ else if (sourceId !== undefined &&
242
+ from !== sourceId &&
243
+ to !== targetId &&
244
+ collinearOverlap(a, b, c, d)) {
245
+ // Worse than a clean crossing: the reader cannot tell the two apart.
246
+ count += 2;
247
+ }
231
248
  return false;
232
249
  });
233
250
  }
234
251
  return count;
235
252
  }
253
+ /** True when two axis-parallel segments lie on one line and share more than a point. */
254
+ function collinearOverlap(a, b, c, d) {
255
+ const shared = (p, q, r, t) => Math.min(Math.max(p, q), Math.max(r, t)) - Math.max(Math.min(p, q), Math.min(r, t)) >
256
+ HIT_TOLERANCE;
257
+ if (Math.abs(a.x - b.x) < 1 && Math.abs(c.x - d.x) < 1 && Math.abs(a.x - c.x) < 1) {
258
+ return shared(a.y, b.y, c.y, d.y);
259
+ }
260
+ if (Math.abs(a.y - b.y) < 1 && Math.abs(c.y - d.y) < 1 && Math.abs(a.y - c.y) < 1) {
261
+ return shared(a.x, b.x, c.x, d.x);
262
+ }
263
+ return false;
264
+ }
236
265
  /** True when the segment a→b passes through `o`, grazing allowed up to HIT_TOLERANCE. */
237
266
  function segmentHits(a, b, o) {
238
267
  const minX = Math.min(a.x, b.x) + HIT_TOLERANCE;
@@ -290,6 +319,22 @@ function forwardCandidates(ctx, source, target, sourceRank, targetRank) {
290
319
  ],
291
320
  ];
292
321
  }
322
+ // A tall container hangs from the task line, so the other end's centre falls
323
+ // within its height: dock there and the flow stays straight.
324
+ if (rightOf) {
325
+ const inTarget = from.y > target.y && from.y < target.y + target.height;
326
+ const inSource = to.y > source.y && to.y < source.y + source.height;
327
+ if (inTarget || inSource) {
328
+ // Both centres inside each other: the smaller shape's line is the row's.
329
+ const y = inTarget && (!inSource || source.height <= target.height) ? from.y : to.y;
330
+ return [
331
+ [
332
+ { x: source.x + source.width, y },
333
+ { x: target.x, y },
334
+ ],
335
+ ];
336
+ }
337
+ }
293
338
  // Same column, different band: drop straight between the two.
294
339
  if (sourceRank !== undefined && sourceRank === targetRank) {
295
340
  const down = to.y > from.y;
@@ -367,8 +412,10 @@ function fromBoundaryCandidates(ctx, source, host, target, targetRank) {
367
412
  { x: gutter, y: to.y },
368
413
  { x: target.x, y: to.y },
369
414
  ];
415
+ // The gutter can already carry another flow's vertical run; beside it is clear.
416
+ const beside = [-1, 1].map((side) => around.map((wp, i) => i === 2 || i === 3 ? { x: gutter + (side * CORRIDOR_SPACING) / 2, y: wp.y } : wp));
370
417
  if (!ahead)
371
- return [around];
418
+ return [around, ...beside];
372
419
  return [
373
420
  [
374
421
  { x: from.x, y: exitY },
@@ -376,6 +423,7 @@ function fromBoundaryCandidates(ctx, source, host, target, targetRank) {
376
423
  { x: target.x, y: to.y },
377
424
  ],
378
425
  around,
426
+ ...beside,
379
427
  ];
380
428
  }
381
429
  return [
@@ -1,4 +1,5 @@
1
1
  import type { BpmnElementType } from "../bpmn/bpmn-model.js";
2
+ import type { AnnotationSide } from "./annotations.js";
2
3
  /** Fixed element dimensions by type. */
3
4
  export declare const ELEMENT_SIZES: Record<string, {
4
5
  width: number;
@@ -86,7 +87,7 @@ export interface LayoutHints {
86
87
  /** Tool grid per ad-hoc sub-process id. */
87
88
  grids?: Map<string, GridHint>;
88
89
  /** Side per text annotation id, overriding the side the packer would choose. */
89
- annotationSides?: Map<string, "above" | "below">;
90
+ annotationSides?: Map<string, AnnotationSide>;
90
91
  }
91
92
  /** Complete layout result for a process. */
92
93
  export interface LayoutResult {
package/llms.txt ADDED
@@ -0,0 +1,9 @@
1
+ # @bpmnkit/core
2
+
3
+ > BPMN 2.0, DMN and Camunda Form SDK for TypeScript. Agents: read the card for your type, not the README.
4
+
5
+ - [AGENTS.md](AGENTS.md): what to read and the rules for all types
6
+ - [BPMN card](agent-cards/bpmn.md): process build script and traps
7
+ - [DMN card](agent-cards/dmn.md): decision table and DRD script and traps
8
+ - [Form card](agent-cards/form.md): form script and traps
9
+ - [Builder reference](builder-reference.md): every builder option
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmnkit/core",
3
- "version": "1.6.1",
3
+ "version": "1.8.0",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -21,9 +21,14 @@
21
21
  "files": [
22
22
  "LICENSE",
23
23
  "README.md",
24
+ "AGENTS.md",
25
+ "llms.txt",
26
+ "agent-cards",
27
+ "builder-reference.md",
24
28
  "dist/**/*.js",
25
29
  "dist/**/*.d.ts"
26
30
  ],
31
+ "agents": "./AGENTS.md",
27
32
  "engines": {
28
33
  "node": ">=20"
29
34
  },