@formicoidea/labre-framework-bpmn 0.37.0 → 0.38.1

package/dist/actions.js

@@ -8,7 +8,7 @@ import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
 import { ASSOCIATION_STROKE, ASSOCIATION_WIDTH, MESSAGE_STROKE, MESSAGE_WIDTH, NODE_LABEL, nodeLabelKey, NODE_SIZE, SEQUENCE_STROKE, SEQUENCE_WIDTH, } from './consts.js';
 import { BPMN_FORMAT_ID } from './export.js';
 import { BPMN_SVG_IMPORT, BPMN_XML_EXPORT, BPMN_XML_FORMAT, BPMN_XML_IMPORT, bpmnBoardFrom, bpmnSafeFilename, } from './interchange.js';
-import { bpmnNodeProps } from './presets.js';
+import { bpmnNodeProps, bpmnPoolProps } from './presets.js';
 import { BPMN_ROLE } from './roles.js';
 /**
  * Standalone creation/activation actions for the BPMN toolbox — lifted out of
@@ -56,13 +56,11 @@ export function createBpmnPool(std) {
     const w = 560;
     const h = 200;
     const { centerX: cx, centerY: cy } = gfx.viewport;
-    const id = surface.addElement({
-        type: 'bpmnPool',
-        // The FRAME the flow objects are drawn in, and a role of its own: a rule
-        // written on the artefacts must never fall on the lane that holds them.
-        role: BPMN_ROLE.pool,
-        xywh: new Bound(cx - w / 2, cy - h / 2, w, h).serialize(),
-    });
+    // What a pool IS lives in one place (`./presets.ts`), beside what a node is
+    // and for the same reason: the shipped cards build their participants from it
+    // too, so a pool laid out by a template and one dropped from the toolbox
+    // cannot say different things. The gesture owns the BOX and nothing else.
+    const id = surface.addElement(bpmnPoolProps({ xywh: new Bound(cx - w / 2, cy - h / 2, w, h).serialize() }));
     finish(gfx, id);
 }
 /**

package/dist/export.d.ts

@@ -213,7 +213,7 @@ export declare const BPMN_SCOPE: {
  * decides the FILENAME and nothing else.
  */
 export interface BpmnExportBoard {
-    /** In document order — which is the tie-break `bpmnPoolOf` breaks on. */
+    /** In document order; `bpmnPoolOf` breaks a tie on the smaller id, not on it. */
     pools: readonly BpmnPoolElementModel[];
     nodes: readonly BpmnNodeElementModel[];
     connectors: readonly ConnectorElementModel[];
@@ -258,10 +258,11 @@ export interface BpmnExportOutcome {
  *   process; with a collaboration it must point at the collaboration, or most
  *   tools draw the flow and none of the pools (spec §12.3.2).
  *
- * Attribution is {@link bpmnPoolOf} and {@link bpmnLaneOf} — the CENTRE against
- * the pool's PLOT, containment only, no nearest-pool fallback. Deliberately the
- * same arithmetic the audit and the validation rules read, so a task the audit
- * reports in "Back office" is in the `lane` named "Back office" here.
+ * Attribution is {@link bpmnPoolOf} and {@link bpmnLaneOf} — WHOLE containment
+ * in the pool, then the CENTRE against the pool's plot for the lane, no
+ * nearest-pool fallback. Deliberately the same arithmetic the audit and the
+ * validation rules read, so a task the audit reports in "Back office" is in the
+ * `lane` named "Back office" here.
  */
 export declare function exportBpmnXml(board: BpmnExportBoard, options?: BpmnExportOptions): string;
 /**

package/dist/export.js

@@ -929,10 +929,11 @@ function edgeScope(element, source, target, ctx) {
  *   process; with a collaboration it must point at the collaboration, or most
  *   tools draw the flow and none of the pools (spec §12.3.2).
  *
- * Attribution is {@link bpmnPoolOf} and {@link bpmnLaneOf} — the CENTRE against
- * the pool's PLOT, containment only, no nearest-pool fallback. Deliberately the
- * same arithmetic the audit and the validation rules read, so a task the audit
- * reports in "Back office" is in the `lane` named "Back office" here.
+ * Attribution is {@link bpmnPoolOf} and {@link bpmnLaneOf} — WHOLE containment
+ * in the pool, then the CENTRE against the pool's plot for the lane, no
+ * nearest-pool fallback. Deliberately the same arithmetic the audit and the
+ * validation rules read, so a task the audit reports in "Back office" is in the
+ * `lane` named "Back office" here.
  */
 export function exportBpmnXml(board, options = {}) {
     return exportBpmnXmlWithWarnings(board, options).text;

package/dist/facts.d.ts

@@ -1,31 +1,19 @@
 import type { BpmnLane, BpmnPoolElementModel } from '@formicoidea/labre-core/model';
 import type { Bound } from '@formicoidea/labre-core/global/gfx';
 /**
- * The pool whose plot contains the bound's centre, or `null`.
+ * The pool an artefact belongs to: the one that WHOLLY CONTAINS its bound
+ * (PF2.4), or `null`.
  *
- * ## Which attribution rule this is, and why it is not the audit's whole one
+ * The pool's ELEMENT bound and not its plot: membership is one question with one
+ * answer across the product, and `containingFrame` is where it is answered — the
+ * same function `containingBackground` uses inside the validation engine, so a
+ * task the engine indicts for hanging off a pool is not reported as being in it.
+ * The name band therefore counts as part of the pool for MEMBERSHIP; it is only
+ * the lane arithmetic below that still subtracts it.
  *
- * The audit attributes in two halves (`attribute()` in `audit.ts`, and
- * `attributeBackground()` in `validation.ts`): the frame that CONTAINS the
- * element, failing that the NEAREST by edge-to-edge gap. This is the containment
- * half only, with the audit's own first-match-in-document-order tie-break —
- * which is the sanctioned reduction, and it is the right one here for two
- * reasons.
- *
- * - The nearest-fallback never returns `null` while a single pool exists on the
- *   board. That is correct for an audit, which has to say something about every
- *   role-carrying element it reports; it is wrong for a fact query, whose whole
- *   value is telling "in this pool" apart from "beside it". A task dropped on
- *   bare canvas is not in a pool, and saying so is the answer.
- * - Containment is tested on the CENTRE against the plot, not on the full
- *   element box against the element box, so this function and {@link bpmnLaneOf}
- *   are the same test at two scales. A laned pool therefore cannot answer "yes,
- *   this pool" and "no lane" for a lane set that covers the plot — the two are
- *   congruent by construction rather than by agreement.
- *
- * Ties — a centre inside two overlapping pools — go to the first pool in the
- * order given, which for a surface is document order. The audit's `attribute()`
- * returns on its first containing frame the same way.
+ * No nearest-pool fallback, unlike the audit's frame attribution: a task dropped
+ * beside a pool is not in it, and inventing one here would put a rule's finding
+ * on a participant the author never drew it on.
  */
 export declare function bpmnPoolOf(pools: readonly BpmnPoolElementModel[], bound: Bound): BpmnPoolElementModel | null;
 /**
@@ -41,6 +29,10 @@ export declare function bpmnPoolOf(pools: readonly BpmnPoolElementModel[], bound
  * not paint. The `BpmnLane` handed back is the model's own row, matched by id,
  * so a caller gets the thing it can rename or resize.
  *
+ * The CENTRE, deliberately unlike {@link bpmnPoolOf}: a task must be wholly in a
+ * pool, but may straddle two lanes and is then read in the one its centre is in.
+ * See the module comment — a board is a container, a band is a reading.
+ *
  * First match in declaration order, so a centre landing exactly ON a divider
  * belongs to the band ABOVE it. Arbitrary in isolation and deliberate together:
  * it is the tie `zoneAt` breaks, and the two must break it the same way.

package/dist/facts.js

@@ -1,4 +1,4 @@
-import { backgroundInstanceZones, backgroundPlot, } from '@formicoidea/labre-core/blocks/surface';
+import { backgroundInstanceZones, backgroundPlot, containingFrame, } from '@formicoidea/labre-core/blocks/surface';
 import { BPMN_POOL_BACKGROUND } from './background.js';
 /**
  * Where a BPMN artefact SITS — the facts, answerable without a `BlockStdScope`.
@@ -16,15 +16,21 @@ import { BPMN_POOL_BACKGROUND } from './background.js';
  * call them, a test can call them with a stub, and the answer cannot depend on
  * which extensions happen to be registered.
  *
- * ## One convention, copied rather than reinvented
+ * ## Two conventions, and the asymmetry between them is the point (PF2.4)
  *
- * Both read the element's CENTRE against ratios of the pool's PLOT, and take the
- * FIRST matching zone in declaration order — the convention `plotRatios` and
- * `zoneAt` already use inside the audit. Copied deliberately and stated here so
- * it stays copied: the day these two disagree with the audit, one component gets
- * two answers about which lane it is in, and no user can be told which is right.
- * The centre also has the property the geometry needs — a task wider than a lane
- * still belongs to exactly one of them.
+ * {@link bpmnPoolOf} asks about MEMBERSHIP and answers with WHOLE containment in
+ * the pool's element bound — the shared `containingFrame`, the same test the
+ * validation engine and the audit use, so one artefact never gets two answers
+ * about which participant it is on.
+ *
+ * {@link bpmnLaneOf} asks about POSITION inside a pool it is already in, and
+ * keeps the CENTRE against ratios of the PLOT, first matching zone in
+ * declaration order — the convention `plotRatios` and `zoneAt` use in the audit.
+ * A lane is a band drawn across a pool, and a task taller than a band still has
+ * to be in exactly one of them.
+ *
+ * So a task must be WHOLLY inside a pool, but may straddle two lanes. That is
+ * deliberate: a board is a container, a band is a reading.
  */
 /**
  * `lane` — the namespace the pool's instance zones report under.
@@ -59,42 +65,23 @@ function within(at, rect) {
         at[1] >= rect.y &&
         at[1] <= rect.y + rect.h);
 }
-/** The whole plot, as the ratios every zone rectangle is expressed in. */
-const WHOLE_PLOT = { x: 0, y: 0, w: 1, h: 1 };
 /**
- * The pool whose plot contains the bound's centre, or `null`.
- *
- * ## Which attribution rule this is, and why it is not the audit's whole one
- *
- * The audit attributes in two halves (`attribute()` in `audit.ts`, and
- * `attributeBackground()` in `validation.ts`): the frame that CONTAINS the
- * element, failing that the NEAREST by edge-to-edge gap. This is the containment
- * half only, with the audit's own first-match-in-document-order tie-break —
- * which is the sanctioned reduction, and it is the right one here for two
- * reasons.
+ * The pool an artefact belongs to: the one that WHOLLY CONTAINS its bound
+ * (PF2.4), or `null`.
  *
- * - The nearest-fallback never returns `null` while a single pool exists on the
- *   board. That is correct for an audit, which has to say something about every
- *   role-carrying element it reports; it is wrong for a fact query, whose whole
- *   value is telling "in this pool" apart from "beside it". A task dropped on
- *   bare canvas is not in a pool, and saying so is the answer.
- * - Containment is tested on the CENTRE against the plot, not on the full
- *   element box against the element box, so this function and {@link bpmnLaneOf}
- *   are the same test at two scales. A laned pool therefore cannot answer "yes,
- *   this pool" and "no lane" for a lane set that covers the plot — the two are
- *   congruent by construction rather than by agreement.
+ * The pool's ELEMENT bound and not its plot: membership is one question with one
+ * answer across the product, and `containingFrame` is where it is answered — the
+ * same function `containingBackground` uses inside the validation engine, so a
+ * task the engine indicts for hanging off a pool is not reported as being in it.
+ * The name band therefore counts as part of the pool for MEMBERSHIP; it is only
+ * the lane arithmetic below that still subtracts it.
  *
- * Ties — a centre inside two overlapping pools — go to the first pool in the
- * order given, which for a surface is document order. The audit's `attribute()`
- * returns on its first containing frame the same way.
+ * No nearest-pool fallback, unlike the audit's frame attribution: a task dropped
+ * beside a pool is not in it, and inventing one here would put a rule's finding
+ * on a participant the author never drew it on.
  */
 export function bpmnPoolOf(pools, bound) {
-    for (const pool of pools) {
-        const at = plotRatios(pool, bound);
-        if (at !== null && within(at, WHOLE_PLOT))
-            return pool;
-    }
-    return null;
+    return containingFrame(bound, pools, pool => pool.elementBound);
 }
 /**
  * The lane of `pool` the bound's centre falls in — `null` when the pool carries
@@ -109,6 +96,10 @@ export function bpmnPoolOf(pools, bound) {
  * not paint. The `BpmnLane` handed back is the model's own row, matched by id,
  * so a caller gets the thing it can rename or resize.
  *
+ * The CENTRE, deliberately unlike {@link bpmnPoolOf}: a task must be wholly in a
+ * pool, but may straddle two lanes and is then read in the one its centre is in.
+ * See the module comment — a board is a container, a band is a reading.
+ *
  * First match in declaration order, so a centre landing exactly ON a divider
  * belongs to the band ABOVE it. Arbitrary in isolation and deliberate together:
  * it is the tie `zoneAt` breaks, and the two must break it the same way.

package/dist/presets.d.ts

@@ -124,6 +124,25 @@ export declare function bpmnNodeProps(kind: BpmnNodeKind, box: {
 }): Record<string, unknown> & {
     type: string;
 };
+/**
+ * One BPMN pool, as the props `surface.addElement` takes.
+ *
+ * The same argument {@link bpmnNodeProps} makes, one artefact over: the palette
+ * hands it a box centred on the viewport and a worked scene hands it the box the
+ * scene lays out, and the element that lands is the same either way. It used to
+ * be spelled out at each site, which is how the shipped cards came to write a
+ * `name` the creation gesture leaves to the model's own default.
+ *
+ * `name` is spread and never defaulted, for the reason `textVerticalAlign` is on
+ * a node: a pool drawn from the toolbox puts no participant name in its Y.Map,
+ * and a scene that names its participants says so explicitly.
+ */
+export declare function bpmnPoolProps(box: {
+    xywh: string;
+    name?: string;
+}): Record<string, unknown> & {
+    type: string;
+};
 /**
  * What a node's kind is worth to an element that ALREADY EXISTS — the same
  * description as {@link bpmnNodeProps}, minus the three things a morph has no

package/dist/presets.js

@@ -1,7 +1,7 @@
 import { FontFamily, SHAPE_TEXT_PADDING, SHAPE_TEXT_VERTICAL_PADDING, ShapeStyle, StrokeStyle, TextAlign, TextFitMode, TextVerticalAlign, } from '@formicoidea/labre-core/model';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
 import { CALL_ACTIVITY_WIDTH, END_WIDTH, EVENT_END, EVENT_START, GROUP_RADIUS, GROUP_STROKE, INNER_FONT_SIZE, LABEL_INSET_RATIO, LABEL_MIN_FONT_SIZE, NEUTRAL_STROKE, NODE_FILL, NODE_SIZE, NODE_STROKE_WIDTH, START_WIDTH, TASK_RADIUS, } from './consts.js';
-import { BPMN_ROLE_OF_KIND } from './roles.js';
+import { BPMN_ROLE, BPMN_ROLE_OF_KIND } from './roles.js';
 /** Per-kind native shape + accent presets (style C). */
 export const NODE_PRESETS = {
     // Events: one ellipse, and the ring weight says start or end. The message and
@@ -255,6 +255,29 @@ export function bpmnNodeProps(kind, box) {
         xywh: box.xywh,
     };
 }
+/**
+ * One BPMN pool, as the props `surface.addElement` takes.
+ *
+ * The same argument {@link bpmnNodeProps} makes, one artefact over: the palette
+ * hands it a box centred on the viewport and a worked scene hands it the box the
+ * scene lays out, and the element that lands is the same either way. It used to
+ * be spelled out at each site, which is how the shipped cards came to write a
+ * `name` the creation gesture leaves to the model's own default.
+ *
+ * `name` is spread and never defaulted, for the reason `textVerticalAlign` is on
+ * a node: a pool drawn from the toolbox puts no participant name in its Y.Map,
+ * and a scene that names its participants says so explicitly.
+ */
+export function bpmnPoolProps(box) {
+    return {
+        type: 'bpmnPool',
+        // The FRAME the flow objects are drawn in, and a role of its own: a rule
+        // written on the artefacts must never fall on the lane that holds them.
+        role: BPMN_ROLE.pool,
+        ...(box.name === undefined ? {} : { name: box.name }),
+        xywh: box.xywh,
+    };
+}
 /**
  * The box {@link bpmnMorphProps} hands {@link bpmnNodeProps} and then throws
  * away. Never written to a document: a morph keeps the geometry the element

package/dist/rules.js

@@ -882,11 +882,11 @@ const activityDeadEnd = {
  *
  * ## What it needs the pool DECLARATION for
  *
- * "Inside the pool" is read against the pool's PLOT, not its element box, and the
- * plot is where the declaration says the flow area starts — the left margin is
- * the participant name band, and a task lying on the band is not in the flow area
- * at all. Carrying `BPMN_POOL_BACKGROUND` here is what makes this rule and
- * `bpmnPoolOf` give one answer to "which pool is this on" instead of two.
+ * "Inside the pool" is WHOLE containment in the pool's element bound (PF2.4) —
+ * the same `containingFrame` `bpmnPoolOf` calls, so this rule and the fact query
+ * give one answer to "which pool is this on" instead of two. The declaration is
+ * carried all the same: it is what the zone half of the family reads, and it is
+ * where the lane geometry lives.
  *
  * ## Silence
  *
@@ -912,8 +912,8 @@ const sequenceFlowStaysHome = {
         reference: 'OMG BPMN 2.0.2 (ISO/IEC 19510) p.40, restated p.502 — Sequence Flows cannot cross a Pool boundary',
     },
     backgroundRole: BPMN_ROLE.pool,
-    // The declaration, so "inside the pool" means inside its FLOW AREA — the
-    // participant name band is not part of it. Same plot `bpmnPoolOf` reads.
+    // The declaration, for the zone half of the family and the lane geometry.
+    // Membership itself is whole containment in the element bound (PF2.4).
     background: BPMN_POOL_BACKGROUND,
     locality: {
         edgeRole: BPMN_ROLE.sequenceFlow,

package/dist/templates/index.js

@@ -1,74 +1,59 @@
-import { makeTemplateSnapshot, surfaceText, } from '@formicoidea/labre-core/gfx/template';
-import { ConnectorMode, FontFamily, PointStyle, ShapeStyle, StrokeStyle, } from '@formicoidea/labre-core/model';
-import { END_WIDTH, EVENT_END, EVENT_START, INNER_FONT_SIZE, MESSAGE_STROKE, MESSAGE_WIDTH, NEUTRAL_STROKE, NODE_FILL, NODE_SIZE, NODE_STROKE_WIDTH, SEQUENCE_STROKE, SEQUENCE_WIDTH, START_WIDTH, TASK_RADIUS, } from '../consts.js';
-import { BPMN_ROLE, BPMN_ROLE_OF_KIND } from '../roles.js';
+import { makeTemplateSnapshot, surfaceText, templateFromCommand, } from '@formicoidea/labre-core/gfx/template';
+import { ConnectorMode, PointStyle, StrokeStyle, } from '@formicoidea/labre-core/model';
+import { bpmnCommands } from '../commands.js';
+import { MESSAGE_STROKE, MESSAGE_WIDTH, NODE_SIZE, SEQUENCE_STROKE, SEQUENCE_WIDTH, } from '../consts.js';
+import { bpmnNodeProps, bpmnPoolProps } from '../presets.js';
+import { BPMN_ROLE } from '../roles.js';
 /**
- * One BPMN flow-object node, as a surface-element JSON entry.
+ * The BPMN palette — DERIVED from the toolbox, one template per artefact
+ * command.
  *
- * Every kind that {@link NodeKind} admits paints its own body natively, as an
- * ellipse, a rounded rect or a diamond. The GLYPH-BODIED kinds (`dataObject`,
- * `dataStore`, `textAnnotation`) do not: they are created unfilled and
- * unstroked and the renderer draws their silhouette, so a card that spelled one
- * out here would insert an invisible rectangle. `group` is out for a neighbouring
- * reason — it is `hollow`, and the branches below all fill. When any of them
- * earns a card, this helper reads `NODE_PRESETS` instead of branching.
+ * Every single-artefact entry below is what its command actually draws, run once
+ * against a recording surface. It used to be a hand-written restatement of the
+ * same artefacts through a private `node()` builder, and it had drifted exactly
+ * as far as a copy drifts: none of the eleven nodes carried the
+ * `textFitMode: Overflow` the pack has written since #160, the events and
+ * gateways had lost their typography on an early return, the labels were English
+ * literals outside the translation seam (#192), and six kinds out of seventeen
+ * had a template at all. Derived, none of that can happen again — and
+ * `templates-parity.unit.spec.ts` re-runs each command and compares, so the day
+ * a creation site changes the palette changes with it.
+ *
+ * The two worked SCENES stay hand-composed: a process end to end and a
+ * two-party message exchange are arrangements of a dozen artefacts, which no
+ * single command draws. They are built on the same presets
+ * ({@link bpmnNodeProps}, {@link bpmnPoolProps}), and the same test checks their
+ * composition AND runs the rule pack over them — which is what caught the
+ * "Message exchange" card violating `bpmn.pool-start-without-end` at insertion.
+ */
+/** The command a derived template is the picture of. Throws rather than skips. */
+function byId(id) {
+    const command = bpmnCommands.find(entry => entry.id === id);
+    if (!command)
+        throw new Error(`[bpmn] templates: no command "${id}"`);
+    return command;
+}
+/**
+ * A scene node, from the same description the toolbox draws from.
+ *
+ * The scene owns the BOX and the words and nothing else — every visual prop
+ * comes from {@link bpmnNodeProps}. Undefined keys are dropped because that is
+ * what `surface.addElement` stores, so a scene artefact stays comparable with a
+ * derived one.
  */
 function node(kind, x, y, text) {
     const { w, h } = NODE_SIZE[kind];
-    const base = {
-        type: 'bpmnNode',
-        kind,
-        // A template must produce the same typed artefacts as the toolbox, or a
-        // process started from a preset would read differently from a hand-drawn
-        // one.
-        role: BPMN_ROLE_OF_KIND[kind],
-        filled: true,
-        fillColor: NODE_FILL,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        xywh: `[${x},${y},${w},${h}]`,
-    };
-    if (kind === 'startEvent')
-        return {
-            ...base,
-            shapeType: 'ellipse',
-            strokeColor: EVENT_START,
-            strokeWidth: START_WIDTH,
-        };
-    if (kind === 'endEvent')
-        return {
-            ...base,
-            shapeType: 'ellipse',
-            strokeColor: EVENT_END,
-            strokeWidth: END_WIDTH,
-        };
-    if (kind === 'gatewayExclusive')
-        return {
-            ...base,
-            shapeType: 'diamond',
-            strokeColor: NEUTRAL_STROKE,
-            strokeWidth: NODE_STROKE_WIDTH,
-        };
-    return {
-        ...base,
-        shapeType: 'rect',
-        radius: TASK_RADIUS,
-        strokeColor: NEUTRAL_STROKE,
-        strokeWidth: NODE_STROKE_WIDTH,
-        text: surfaceText(text ?? 'Task'),
-        color: NEUTRAL_STROKE,
-        fontFamily: FontFamily.Inter,
-        fontSize: INNER_FONT_SIZE,
-        textAlign: 'center',
-    };
+    return defined({
+        ...bpmnNodeProps(kind, { xywh: `[${x},${y},${w},${h}]` }),
+        // A snapshot carries a serialized `Y.Text`, never a bare string.
+        ...(text === undefined ? {} : { text: surfaceText(text) }),
+    });
 }
-function pool(x, y, w, h, name = 'Pool') {
-    return {
-        type: 'bpmnPool',
-        role: BPMN_ROLE.pool,
-        name,
-        xywh: `[${x},${y},${w},${h}]`,
-    };
+/** A scene participant, from the same description the toolbox draws from. */
+const pool = (x, y, w, h, name) => defined(bpmnPoolProps({ xywh: `[${x},${y},${w},${h}]`, name }));
+/** Drop the keys a preset left undefined — what `addElement` would store. */
+function defined(props) {
+    return Object.fromEntries(Object.entries(props).filter(([, value]) => value !== undefined));
 }
 /** A sequence-flow connector; ids are remapped on insert. */
 function seq(source, target) {
@@ -121,6 +106,10 @@ function msg(source, target) {
  * that", and a stroke attached to neither end has no this and no that to say it
  * about. Drawing it with the sequence-flow tool, or dropping this one and then
  * attaching both of its ends, is what makes it a statement.
+ *
+ * Hand-written, and the one artefact card that cannot derive:
+ * `bpmn.sequenceFlowTool` ACTIVATES a tool rather than drawing anything, so
+ * there is nothing to record — the user draws it.
  */
 function freeSeq() {
     return {
@@ -135,86 +124,139 @@ function freeSeq() {
         target: { position: [140, 0] },
     };
 }
-const single = (el) => ({
-    a: el,
-});
-const PREVIEW_ATTRS = 'width="100%" height="100%" viewBox="0 0 135 80" xmlns="http://www.w3.org/2000/svg"';
+/* ── Previews ─────────────────────────────────────────────────────────────
+ *
+ * One 135×80 sketch per card, in the toolbar glyphs' own shapes
+ * (`../toolbar/icons.ts`). A preview has one job, which is to look like what
+ * lands on the board.
+ */
+const A = 'width="100%" height="100%" viewBox="0 0 135 80" xmlns="http://www.w3.org/2000/svg"';
+/** An event: the ring weight says start or end, the glyph says what triggers it. */
+const eventPreview = (stroke, width, glyph = '') => `<svg ${A} fill="none"><circle cx="67" cy="40" r="20" stroke="${stroke}" stroke-width="${width}"/>${glyph}</svg>`;
+/** An activity: one rounded rectangle, and a marker tells the kinds apart. */
+const taskPreview = (glyph = '', width = 2.4) => `<svg ${A} fill="none"><rect x="34" y="24" width="66" height="32" rx="6" stroke="#262626" stroke-width="${width}"/>${glyph}</svg>`;
+/** A gateway: one diamond, one marker each. */
+const gatewayPreview = (marker) => `<svg ${A} fill="none"><path d="M67 16 L92 40 L67 64 L42 40 Z" stroke="#262626" stroke-width="2.4" stroke-linejoin="round"/><path d="${marker}" stroke="#262626" stroke-width="2.2" stroke-linecap="round"/></svg>`;
+const ENVELOPE = '<rect x="59" y="35" width="16" height="11" stroke="#262626" stroke-width="1.4"/><path d="M59 35 L67 42 L75 35" stroke="#262626" stroke-width="1.4" stroke-linejoin="round"/>';
+const CLOCK = '<circle cx="67" cy="40" r="9" stroke="#262626" stroke-width="1.4"/><path d="M67 40 V33 M67 40 L72 43" stroke="#262626" stroke-width="1.4" stroke-linecap="round"/>';
+/** The collapsed `[+]`, on the activity's bottom edge — sub-process and call alike. */
+const COLLAPSED = '<rect x="61" y="44" width="12" height="12" stroke="#262626" stroke-width="1.4"/><path d="M67 47 V53 M64 50 H70" stroke="#262626" stroke-width="1.4" stroke-linecap="round"/>';
 const previews = {
-    process: `<svg ${PREVIEW_ATTRS} fill="none"><circle cx="16" cy="40" r="8" stroke="#43a06b" stroke-width="2"/><rect x="34" y="31" width="26" height="18" rx="3" stroke="#262626" stroke-width="1.6"/><path d="M78 31 L88 40 L78 49 L68 40 Z" stroke="#262626" stroke-width="1.4"/><path d="M73 37 L83 43 M83 37 L73 43" stroke="#262626" stroke-width="1.2"/><circle cx="118" cy="40" r="8" stroke="#cf5648" stroke-width="3"/><path d="M24 40 H34 M60 40 H68 M88 40 H110" stroke="#262626" stroke-width="1.2"/></svg>`,
-    startEvent: `<svg ${PREVIEW_ATTRS} fill="none"><circle cx="67" cy="40" r="20" stroke="#43a06b" stroke-width="3"/></svg>`,
-    endEvent: `<svg ${PREVIEW_ATTRS} fill="none"><circle cx="67" cy="40" r="20" stroke="#cf5648" stroke-width="5"/></svg>`,
-    task: `<svg ${PREVIEW_ATTRS} fill="none"><rect x="34" y="24" width="66" height="32" rx="6" stroke="#262626" stroke-width="2.4"/></svg>`,
-    gateway: `<svg ${PREVIEW_ATTRS} fill="none"><path d="M67 16 L92 40 L67 64 L42 40 Z" stroke="#262626" stroke-width="2.4" stroke-linejoin="round"/><path d="M58 31 L76 49 M76 31 L58 49" stroke="#262626" stroke-width="2.2" stroke-linecap="round"/></svg>`,
-    sequence: `<svg ${PREVIEW_ATTRS} fill="none"><path d="M24 40 H96" stroke="#262626" stroke-width="2.4" stroke-linecap="round"/><path d="M94 33 L108 40 L94 47 Z" fill="#262626"/></svg>`,
-    pool: `<svg ${PREVIEW_ATTRS} fill="none"><rect x="14" y="20" width="107" height="40" rx="3" stroke="#262626" stroke-width="2"/><path d="M30 20 V60" stroke="#262626" stroke-width="1.8"/><rect x="14" y="20" width="16" height="40" fill="#f4f4f5"/><path d="M30 20 V60" stroke="#262626" stroke-width="1.8"/></svg>`,
+    process: `<svg ${A} fill="none"><circle cx="16" cy="40" r="8" stroke="#43a06b" stroke-width="2"/><rect x="34" y="31" width="26" height="18" rx="3" stroke="#262626" stroke-width="1.6"/><path d="M78 31 L88 40 L78 49 L68 40 Z" stroke="#262626" stroke-width="1.4"/><path d="M73 37 L83 43 M83 37 L73 43" stroke="#262626" stroke-width="1.2"/><circle cx="118" cy="40" r="8" stroke="#cf5648" stroke-width="3"/><path d="M24 40 H34 M60 40 H68 M88 40 H110" stroke="#262626" stroke-width="1.2"/></svg>`,
+    startEvent: eventPreview('#43a06b', 3),
+    startEventMessage: eventPreview('#43a06b', 3, ENVELOPE),
+    startEventTimer: eventPreview('#43a06b', 3, CLOCK),
+    endEvent: eventPreview('#cf5648', 5),
+    endEventMessage: eventPreview('#cf5648', 5, ENVELOPE),
+    endEventTerminate: eventPreview('#cf5648', 5, '<circle cx="67" cy="40" r="8" fill="#262626"/>'),
+    task: taskPreview(),
+    taskUser: taskPreview('<circle cx="41" cy="31" r="2.6" stroke="#262626" stroke-width="1.2"/><path d="M37.4 38 a3.6 3.6 0 0 1 7.2 0" stroke="#262626" stroke-width="1.2"/>'),
+    taskService: taskPreview('<circle cx="41" cy="32" r="3.4" stroke="#262626" stroke-width="1.2"/><circle cx="41" cy="32" r="1" fill="#262626"/><path d="M41 27.4 V29 M41 35 V36.6 M36.4 32 H38 M44 32 H45.6" stroke="#262626" stroke-width="1.2" stroke-linecap="round"/>'),
+    subProcess: taskPreview(COLLAPSED),
+    // The thick border IS the distinction: this box stands for a process defined
+    // elsewhere (`presets.ts`, `CALL_ACTIVITY_WIDTH`).
+    callActivity: taskPreview(COLLAPSED, 4.5),
+    gateway: gatewayPreview('M58 31 L76 49 M76 31 L58 49'),
+    gatewayParallel: gatewayPreview('M67 30 V50 M57 40 H77'),
+    dataObject: `<svg ${A} fill="none"><path d="M52 14 H76 L88 26 V66 H52 Z" stroke="#262626" stroke-width="2.2" stroke-linejoin="round"/><path d="M76 14 V26 H88" stroke="#262626" stroke-width="1.8" stroke-linejoin="round"/></svg>`,
+    dataStore: `<svg ${A} fill="none"><path d="M48 22 V58 C48 62 56 65 67 65 C78 65 86 62 86 58 V22" stroke="#262626" stroke-width="2.2" stroke-linejoin="round"/><ellipse cx="67" cy="22" rx="19" ry="6" stroke="#262626" stroke-width="2.2"/></svg>`,
+    textAnnotation: `<svg ${A} fill="none"><path d="M46 16 H36 V64 H46" stroke="#262626" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/><path d="M54 28 H100 M54 40 H100 M54 52 H86" stroke="#262626" stroke-width="1.8" stroke-linecap="round"/></svg>`,
+    group: `<svg ${A} fill="none"><rect x="18" y="12" width="99" height="56" rx="10" stroke="#8e8d91" stroke-width="2.2" stroke-dasharray="7 5"/></svg>`,
+    sequence: `<svg ${A} fill="none"><path d="M24 40 H96" stroke="#262626" stroke-width="2.4" stroke-linecap="round"/><path d="M94 33 L108 40 L94 47 Z" fill="#262626"/></svg>`,
+    pool: `<svg ${A} fill="none"><rect x="14" y="20" width="107" height="40" rx="3" stroke="#262626" stroke-width="2"/><path d="M30 20 V60" stroke="#262626" stroke-width="1.8"/><rect x="14" y="20" width="16" height="40" fill="#f4f4f5"/><path d="M30 20 V60" stroke="#262626" stroke-width="1.8"/></svg>`,
     // Two participants stacked, and the dashed line between them is the whole
     // point of the card: a message flow is the one arrow that crosses a pool.
     // Its source terminator is a FILLED disc, matching what `renderCircle`
     // actually paints rather than the hollow ring the norm asks for — a preview
     // has one job, which is to look like what lands on the board.
-    messageExchange: `<svg ${PREVIEW_ATTRS} fill="none"><rect x="14" y="8" width="107" height="27" rx="3" stroke="#262626" stroke-width="1.6"/><rect x="14" y="8" width="11" height="27" fill="#f4f4f5"/><path d="M25 8 V35" stroke="#262626" stroke-width="1.4"/><rect x="14" y="45" width="107" height="27" rx="3" stroke="#262626" stroke-width="1.6"/><rect x="14" y="45" width="11" height="27" fill="#f4f4f5"/><path d="M25 45 V72" stroke="#262626" stroke-width="1.4"/><circle cx="36" cy="21.5" r="4.5" stroke="#43a06b" stroke-width="1.6"/><rect x="52" y="14" width="30" height="15" rx="3" stroke="#262626" stroke-width="1.6"/><rect x="52" y="51" width="30" height="15" rx="3" stroke="#262626" stroke-width="1.6"/><path d="M45 21.5 H52" stroke="#262626" stroke-width="1.4"/><circle cx="67" cy="31.5" r="2.2" fill="#262626"/><path d="M67 34 V48" stroke="#262626" stroke-width="1.4" stroke-dasharray="3 2.4"/><path d="M64 46 L67 50 L70 46" stroke="#262626" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+    messageExchange: `<svg ${A} fill="none"><rect x="14" y="8" width="107" height="27" rx="3" stroke="#262626" stroke-width="1.6"/><rect x="14" y="8" width="11" height="27" fill="#f4f4f5"/><path d="M25 8 V35" stroke="#262626" stroke-width="1.4"/><rect x="14" y="45" width="107" height="27" rx="3" stroke="#262626" stroke-width="1.6"/><rect x="14" y="45" width="11" height="27" fill="#f4f4f5"/><path d="M25 45 V72" stroke="#262626" stroke-width="1.4"/><circle cx="33" cy="21.5" r="4.5" stroke="#43a06b" stroke-width="1.6"/><rect x="46" y="14" width="26" height="15" rx="3" stroke="#262626" stroke-width="1.6"/><circle cx="88" cy="21.5" r="4.5" stroke="#cf5648" stroke-width="2.6"/><rect x="46" y="51" width="26" height="15" rx="3" stroke="#262626" stroke-width="1.6"/><path d="M41 21.5 H46 M72 21.5 H83" stroke="#262626" stroke-width="1.4"/><circle cx="59" cy="31.5" r="2.2" fill="#262626"/><path d="M59 34 V48" stroke="#262626" stroke-width="1.4" stroke-dasharray="3 2.4"/><path d="M56 46 L59 50 L62 46" stroke="#262626" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+};
+/* ── The two worked scenes ────────────────────────────────────────────────── */
+/** A hand-composed card — what is left once the artefacts are derived. */
+const scene = (name, preview, elements) => ({
+    name,
+    type: 'template',
+    preview,
+    content: makeTemplateSnapshot(elements, name),
+});
+const process = {
+    pool: pool(0, 0, 640, 200, 'Process'),
+    start: node('startEvent', 40, 72),
+    task1: node('task', 116, 64, 'Submit request'),
+    gw: node('gatewayExclusive', 272, 64),
+    task2: node('task', 376, 20, 'Fulfil'),
+    task3: node('task', 376, 124, 'Reject'),
+    end: node('endEvent', 556, 72),
+    c1: seq('start', 'task1'),
+    c2: seq('task1', 'gw'),
+    c3: seq('gw', 'task2'),
+    c4: seq('gw', 'task3'),
+    c5: seq('task2', 'end'),
+    c6: seq('task3', 'end'),
 };
 /**
- * The BPMN basics: two worked scenes — a process end to end and a two-party
- * message exchange — plus a prefab for each of the lean artefacts.
+ * Two participants, and the one arrow that is allowed to cross between them.
+ *
+ * The card exists because the message flow is the piece of BPMN people get
+ * wrong first: a sequence flow may never leave its pool, and the thing that
+ * does leave is a different statement with a different line. Laying the two
+ * pools out one above the other and drawing both flows once is the shortest
+ * way to show that — the solid arrow stays home, the dashed one crosses.
+ *
+ * Stacked vertically with a 40-unit gutter, so the message flow is a straight
+ * orthogonal drop between two tasks that already line up.
+ *
+ * ## The end event, which is not decoration
+ *
+ * The customer pool shipped with a start event and no end, which is a verbatim
+ * violation of BPMN 2.0.2 p.246 and of `bpmn.pool-start-without-end` — a
+ * `warning` the moment anybody switched the card to the descriptive profile.
+ * Factory content teaching the mistake the rule pack reports is the worst
+ * possible first BPMN diagram, and nothing in the repository compared the two
+ * until this slice ran the rules over the shipped cards. The customer's process
+ * now closes where it should: order placed, then done.
  */
-function bpmnTemplates() {
-    const process = {
-        pool: pool(0, 0, 640, 200, 'Process'),
-        start: node('startEvent', 40, 72),
-        task1: node('task', 116, 64, 'Submit request'),
-        gw: node('gatewayExclusive', 272, 64),
-        task2: node('task', 376, 20, 'Fulfil'),
-        task3: node('task', 376, 124, 'Reject'),
-        end: node('endEvent', 556, 72),
-        c1: seq('start', 'task1'),
-        c2: seq('task1', 'gw'),
-        c3: seq('gw', 'task2'),
-        c4: seq('gw', 'task3'),
-        c5: seq('task2', 'end'),
-        c6: seq('task3', 'end'),
-    };
-    /**
-     * Two participants, and the one arrow that is allowed to cross between them.
-     *
-     * The card exists because the message flow is the piece of BPMN people get
-     * wrong first: a sequence flow may never leave its pool, and the thing that
-     * does leave is a different statement with a different line. Laying the two
-     * pools out one above the other and drawing both flows once is the shortest
-     * way to show that — the solid arrow stays home, the dashed one crosses.
-     *
-     * Stacked vertically with a 40-unit gutter, so the message flow is a straight
-     * orthogonal drop between two tasks that already line up.
-     */
-    const messageExchange = {
-        customer: pool(0, 0, 640, 200, 'Customer'),
-        supplier: pool(0, 240, 640, 200, 'Supplier'),
-        start: node('startEvent', 40, 72),
-        ask: node('taskUser', 140, 64, 'Place order'),
-        answer: node('taskService', 140, 304, 'Confirm order'),
-        // Inside the first participant: what happens, and in what order.
-        inside: seq('start', 'ask'),
-        // Across the two: who told whom.
-        across: msg('ask', 'answer'),
-    };
-    const t = (name, preview, elements) => ({
-        name,
-        type: 'template',
-        preview,
-        content: makeTemplateSnapshot(elements, name),
-    });
-    return [
-        t('Simple process', previews.process, process),
-        t('Message exchange', previews.messageExchange, messageExchange),
-        t('Start event', previews.startEvent, single(node('startEvent', 0, 0))),
-        t('End event', previews.endEvent, single(node('endEvent', 0, 0))),
-        t('Task', previews.task, single(node('task', 0, 0))),
-        t('Exclusive gateway', previews.gateway, single(node('gatewayExclusive', 0, 0))),
-        t('Sequence flow', previews.sequence, single(freeSeq())),
-        t('Pool', previews.pool, single(pool(0, 0, 560, 200))),
-    ];
-}
+const messageExchange = {
+    customer: pool(0, 0, 640, 200, 'Customer'),
+    supplier: pool(0, 240, 640, 200, 'Supplier'),
+    start: node('startEvent', 40, 72),
+    ask: node('taskUser', 140, 64, 'Place order'),
+    done: node('endEvent', 320, 72),
+    answer: node('taskService', 140, 304, 'Confirm order'),
+    // Inside the first participant: what happens, and in what order.
+    inside: seq('start', 'ask'),
+    closes: seq('ask', 'done'),
+    // Across the two: who told whom.
+    across: msg('ask', 'answer'),
+};
 export const bpmnTemplateCategory = {
     name: 'BPMN',
-    templates: bpmnTemplates(),
+    templates: [
+        scene('Simple process', previews.process, process),
+        scene('Message exchange', previews.messageExchange, messageExchange),
+        /* ── The core: a drawable process, from the first click ─────────────── */
+        templateFromCommand(byId('bpmn.addStartEvent'), previews.startEvent),
+        templateFromCommand(byId('bpmn.addEndEvent'), previews.endEvent),
+        templateFromCommand(byId('bpmn.addTask'), previews.task),
+        templateFromCommand(byId('bpmn.addExclusiveGateway'), previews.gateway),
+        scene('Sequence flow', previews.sequence, { a: freeSeq() }),
+        templateFromCommand(byId('bpmn.addPool'), previews.pool),
+        /* ── Activities ─────────────────────────────────────────────────────── */
+        templateFromCommand(byId('bpmn.addUserTask'), previews.taskUser),
+        templateFromCommand(byId('bpmn.addServiceTask'), previews.taskService),
+        templateFromCommand(byId('bpmn.addSubProcess'), previews.subProcess),
+        templateFromCommand(byId('bpmn.addCallActivity'), previews.callActivity),
+        /* ── The other gateway ──────────────────────────────────────────────── */
+        templateFromCommand(byId('bpmn.addParallelGateway'), previews.gatewayParallel),
+        /* ── Event variants ─────────────────────────────────────────────────── */
+        templateFromCommand(byId('bpmn.addMessageStartEvent'), previews.startEventMessage),
+        templateFromCommand(byId('bpmn.addTimerStartEvent'), previews.startEventTimer),
+        templateFromCommand(byId('bpmn.addMessageEndEvent'), previews.endEventMessage),
+        templateFromCommand(byId('bpmn.addTerminateEndEvent'), previews.endEventTerminate),
+        /* ── Data, and what an author writes ON the picture ──────────────────── */
+        templateFromCommand(byId('bpmn.addDataObject'), previews.dataObject),
+        templateFromCommand(byId('bpmn.addDataStore'), previews.dataStore),
+        templateFromCommand(byId('bpmn.addTextAnnotation'), previews.textAnnotation),
+        templateFromCommand(byId('bpmn.addGroup'), previews.group),
+    ],
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-framework-bpmn",
   "description": "Labre bpmn framework for @formicoidea/labre-core.",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",
@@ -31,7 +31,7 @@
     "dist"
   ],
   "dependencies": {
-    "@formicoidea/labre-core": "0.37.0",
+    "@formicoidea/labre-core": "0.38.1",
     "lit": "^3.2.0"
   }
 }