@formicoidea/labre-framework-bpmn 0.31.0 → 0.33.0

package/dist/index.d.ts

@@ -1 +1,14 @@
-export {};
+export { BPMN_POOL_BACKGROUND } from './background.js';
+export { bpmnBoardOf } from './actions.js';
+export { materializeBpmnImport, reportBpmnImport } from './actions.js';
+export { bpmnCommandIcons, bpmnCommands } from './commands.js';
+export { BPMN_FORMAT_ID, BPMN_NS, BPMN_XML_OF_KIND, type BpmnExportBoard, type BpmnExportOptions, type BpmnExportOutcome, type BpmnXmlMapping, exportBpmnXml, exportBpmnXmlWithWarnings, isNcName, toNcName, } from './export.js';
+export { BPMN_KIND_OF_XML, BPMN_QUARANTINE_REASON, importBpmnXml, } from './import.js';
+export { bpmnMorphClears, bpmnMorphProps, bpmnNodeProps, type BpmnNodePreset, NODE_PRESETS, } from './presets.js';
+export { BPMN_MORPH_FAMILIES, BPMN_MORPH_SPEC } from './morph.js';
+export { BPMN_INTERCHANGE, BPMN_SVG_FORMAT, BPMN_SVG_IMPORT, BPMN_XML_EXPORT, BPMN_XML_EXTENSION, BPMN_XML_IMPORT, BPMN_XML_FORMAT, BPMN_XML_MIME, bpmnBoardFrom, bpmnSafeFilename, } from './interchange.js';
+export { bpmnLaneOf, bpmnPoolOf } from './facts.js';
+export { BPMN_PROFILES } from './profiles.js';
+export { BPMN_ROLE, BPMN_ROLE_OF_KIND, BPMN_ROLES, type BpmnRole, type BpmnRoleId, } from './roles.js';
+export { BPMN_RULES, BPMN_SEQUENCE_MATRIX } from './rules.js';
+export { bpmnTranslationEntries } from './translations.js';

package/dist/index.js

@@ -1 +1,46 @@
-export {};
+// The declaration IS the pool: what it looks like, where its plot is and how
+// its lanes divide that plot are all read off this one value (`docs/adr/0009`
+// on why a framework declares rather than draws). Exported so a host — and the
+// audit's own consumers — can answer those questions without a canvas.
+export { BPMN_POOL_BACKGROUND } from './background.js';
+// Everything on the surface the exporter speaks about, in document order — the
+// half of the export that needs an editor, kept apart from the half that does
+// not so a host can substitute either.
+export { bpmnBoardOf } from './actions.js';
+// …and the mirror half of the import: the reader is pure, and THIS is the one
+// thing its caller owes it — the surface mints ids, so a connector's endpoints
+// arrive naming the source file's and are rewritten from the map the returned
+// array already carries (`docs/adr/0012`, D3). Exported so the command, the
+// chromium round trip and a host embedding the reader all write a board the
+// same way.
+export { materializeBpmnImport, reportBpmnImport } from './actions.js';
+export { bpmnCommandIcons, bpmnCommands } from './commands.js';
+// The board as a BPMN 2.0 interchange document. A pure function — element
+// models in, XML out — so a host can export a board it never rendered, and the
+// kind → element table it is built on is readable without running it.
+export { BPMN_FORMAT_ID, BPMN_NS, BPMN_XML_OF_KIND, exportBpmnXml, exportBpmnXmlWithWarnings, isNcName, toNcName, } from './export.js';
+// …and the same file, back as a board. A pure function too — text in, element
+// PROPS out, never live models — so labre-mcp reads a `.bpmn` through the one
+// implementation the editor reads it through (`docs/adr/0012`, P3).
+export { BPMN_KIND_OF_XML, BPMN_QUARANTINE_REASON, importBpmnXml, } from './import.js';
+// What an artefact is BORN as, shared by the palette and the importer so a task
+// read out of a file and a task drawn by hand are one element in the document —
+// and, since the morph, by the toolbar that says one artefact more precisely.
+export { bpmnMorphClears, bpmnMorphProps, bpmnNodeProps, NODE_PRESETS, } from './presets.js';
+// What an artefact may BECOME: the declared families, and the spec the generic
+// morph module is registered with. Data a host can read without an editor.
+export { BPMN_MORPH_FAMILIES, BPMN_MORPH_SPEC } from './morph.js';
+// BPMN's entries in the interchange registry (`docs/adr/0012`) — `.bpmn` out,
+// `.bpmn` in, and the visual-tier SVG fallback. Exported whole so a host can
+// ask what BPMN can read and write without mounting an editor, and call it
+// without one either.
+export { BPMN_INTERCHANGE, BPMN_SVG_FORMAT, BPMN_SVG_IMPORT, BPMN_XML_EXPORT, BPMN_XML_EXTENSION, BPMN_XML_IMPORT, BPMN_XML_FORMAT, BPMN_XML_MIME, bpmnBoardFrom, bpmnSafeFilename, } from './interchange.js';
+// Where an artefact sits, without a `BlockStdScope`: the same pool and lane
+// attribution the audit computes, answerable by a rule, a host or a test.
+export { bpmnLaneOf, bpmnPoolOf } from './facts.js';
+// The levels of requirement, and the rules they arbitrate: DATA a host can read,
+// ship and reason about without an editor.
+export { BPMN_PROFILES } from './profiles.js';
+export { BPMN_ROLE, BPMN_ROLE_OF_KIND, BPMN_ROLES, } from './roles.js';
+export { BPMN_RULES, BPMN_SEQUENCE_MATRIX } from './rules.js';
+export { bpmnTranslationEntries } from './translations.js';

package/dist/interchange.d.ts

@@ -0,0 +1,109 @@
+import type { InterchangeCapability, InterchangeExportCapability, InterchangeFormat, InterchangeImportCapability } from '@formicoidea/labre-core/blocks/surface';
+import type { GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+import { type BpmnExportBoard } from './export.js';
+/**
+ * BPMN's entries in the interchange registry (`docs/adr/0012`, P1).
+ *
+ * Both directions of one format, declared as two capabilities and not as one
+ * symmetric thing: `.bpmn` OUT shipped in #149, `.bpmn` IN is the worked
+ * example D1–D6 specifies, and each makes its own promises. The registry says
+ * so in the only way it can — a row per triple.
+ *
+ * They share the FORMAT object, deliberately. `bpmn` is the id under which
+ * foreign matter rides on an element (D2), so a reader and a writer that
+ * disagreed about it would write payloads the other could not find; there is
+ * one `BPMN_XML_FORMAT` and both point at it.
+ *
+ * Everything here is pure. Neither serializer nor parser has ever had a `std`
+ * in sight, and this file adds no editor to either: it picks the artefacts the
+ * writer speaks about out of a surface's elements, and hands the reader's
+ * output straight back to whoever asked for it.
+ */
+/**
+ * BPMN 2.0 XML. **Semantic** — the file carries a model, not a picture, so it
+ * takes the whole preservation contract the day an importer is written.
+ *
+ * `application/xml` and not `text/xml`: the file is not meant to be read as
+ * text by whatever opens it, and `.bpmn` is the extension every BPMN tool
+ * watches for.
+ *
+ * `.xml` rides along BEHIND it, and the order is the whole of the difference:
+ * the first extension is the one a download is given, so Labre still writes
+ * `.bpmn`, and the rest are what a picker offers and what an auto-detecting
+ * host indexes on. Half the tools in the wild write the same bytes under the
+ * generic extension, and a filter that refused them would refuse a valid
+ * process for the sake of a filename — the same argument the shared `FileTypes`
+ * table made when this filter lived there, kept now that the filter is built
+ * from the format itself. What the file actually IS is decided by the reader,
+ * which throws on anything that is not a BPMN `<definitions>`.
+ */
+export declare const BPMN_XML_EXTENSION = ".bpmn";
+export declare const BPMN_XML_MIME = "application/xml";
+export declare const BPMN_XML_FORMAT: InterchangeFormat;
+/**
+ * The artefacts the exporter speaks about, picked out of a surface's elements
+ * and kept in the order they were given.
+ *
+ * Document order matters twice and both times for the same reason: `bpmnPoolOf`
+ * gives a centre inside two overlapping pools to the FIRST one, and the audit's
+ * `attribute()` does the same. Sorting here would make the export disagree with
+ * the badge the user can see.
+ */
+export declare function bpmnBoardFrom(elements: readonly GfxPrimitiveElementModel[]): BpmnExportBoard;
+/**
+ * A name a file system will accept, minus the extension.
+ *
+ * Every character a file system reserves becomes `-`, whitespace runs collapse,
+ * and the result is capped: `process` is a better download than one a browser
+ * silently refuses.
+ *
+ * The trailing `[. ]` trim is the Windows tail case and it is not decorative: a
+ * board called "Order to cash." would otherwise download as
+ * `Order to cash..bpmn`, and Windows strips trailing dots and spaces from a
+ * name anyway — so the extension is what would get eaten. Trimmed AFTER the
+ * cap, because the cap can create one.
+ */
+export declare function bpmnSafeFilename(raw: string | undefined): string;
+/** `bpmn:bpmn:export` — the registry's first capability. */
+export declare const BPMN_XML_EXPORT: InterchangeExportCapability;
+/**
+ * `bpmn:bpmn:import` — a `.bpmn` file as a board.
+ *
+ * A thin adapter over {@link importBpmnXml} and nothing else, which is the
+ * whole of what a capability is: the parser is a pure function of a string, so
+ * the registry entry has nothing to add to it and deliberately adds nothing.
+ * A reader that threw its arms around a surface here would be a reader
+ * labre-mcp could not call.
+ */
+export declare const BPMN_XML_IMPORT: InterchangeImportCapability;
+/**
+ * SVG. **Visual** — the file carries a rendering, not a model.
+ *
+ * A separate format object from `BPMN_XML_FORMAT` and deliberately not a shared
+ * singleton with Wardley's: ADR 0012's unit is the TRIPLE, and the ADR
+ * explicitly rejects "one capability per format, with the framework inferred
+ * from the file" — a `.svg` is read by several frameworks and the inference is
+ * exactly the guess the ADR forbids everywhere else. The three constants come
+ * from the parser's own package so the two declarations cannot drift into
+ * disagreeing about the extension or the mime a picker filters on.
+ */
+export declare const BPMN_SVG_FORMAT: InterchangeFormat;
+/**
+ * `bpmn:svg:import` — an SVG as a sketch, best effort.
+ *
+ * **The heuristics statement and the known failure modes this capability owes
+ * (ADR 0012, open question 2) are the module documentation of
+ * `packages/affine/blocks/surface/src/extensions/svg-sketch.ts`.** They are
+ * written once, there, because BPMN and Wardley wrap the SAME parser and
+ * therefore make the same guesses; a framework that ever wants narrower or
+ * wider recognition writes its own parser and its own paragraph beside it.
+ *
+ * What lands is a level-1 sketch (ADR 0007) — plain shapes, brush strokes and
+ * editable free text — that the author then PROMOTES into BPMN artefacts.
+ * Nothing here decides that a rounded rectangle in somebody's picture was a
+ * task, and no `interchange` payload is written, because a visual round-trip
+ * would be a re-render (P2).
+ */
+export declare const BPMN_SVG_IMPORT: InterchangeImportCapability;
+/** Everything BPMN registers, in one list the view extension can hand over. */
+export declare const BPMN_INTERCHANGE: readonly InterchangeCapability[];

package/dist/interchange.js

@@ -0,0 +1,191 @@
+import { interchangeCapabilityId, parseSvgSketch, SVG_SKETCH_EXTENSION, SVG_SKETCH_FORMAT_ID, SVG_SKETCH_MIME, } from '@formicoidea/labre-core/blocks/surface';
+import { BpmnNodeElementModel, BpmnPoolElementModel, ConnectorElementModel, } from '@formicoidea/labre-core/model';
+import { BPMN_FORMAT_ID, exportBpmnXmlWithWarnings, } from './export.js';
+import { importBpmnXml } from './import.js';
+/**
+ * BPMN's entries in the interchange registry (`docs/adr/0012`, P1).
+ *
+ * Both directions of one format, declared as two capabilities and not as one
+ * symmetric thing: `.bpmn` OUT shipped in #149, `.bpmn` IN is the worked
+ * example D1–D6 specifies, and each makes its own promises. The registry says
+ * so in the only way it can — a row per triple.
+ *
+ * They share the FORMAT object, deliberately. `bpmn` is the id under which
+ * foreign matter rides on an element (D2), so a reader and a writer that
+ * disagreed about it would write payloads the other could not find; there is
+ * one `BPMN_XML_FORMAT` and both point at it.
+ *
+ * Everything here is pure. Neither serializer nor parser has ever had a `std`
+ * in sight, and this file adds no editor to either: it picks the artefacts the
+ * writer speaks about out of a surface's elements, and hands the reader's
+ * output straight back to whoever asked for it.
+ */
+/* ── The format ───────────────────────────────────────────────────────── */
+/**
+ * BPMN 2.0 XML. **Semantic** — the file carries a model, not a picture, so it
+ * takes the whole preservation contract the day an importer is written.
+ *
+ * `application/xml` and not `text/xml`: the file is not meant to be read as
+ * text by whatever opens it, and `.bpmn` is the extension every BPMN tool
+ * watches for.
+ *
+ * `.xml` rides along BEHIND it, and the order is the whole of the difference:
+ * the first extension is the one a download is given, so Labre still writes
+ * `.bpmn`, and the rest are what a picker offers and what an auto-detecting
+ * host indexes on. Half the tools in the wild write the same bytes under the
+ * generic extension, and a filter that refused them would refuse a valid
+ * process for the sake of a filename — the same argument the shared `FileTypes`
+ * table made when this filter lived there, kept now that the filter is built
+ * from the format itself. What the file actually IS is decided by the reader,
+ * which throws on anything that is not a BPMN `<definitions>`.
+ */
+export const BPMN_XML_EXTENSION = '.bpmn';
+export const BPMN_XML_MIME = 'application/xml';
+export const BPMN_XML_FORMAT = {
+    id: BPMN_FORMAT_ID,
+    tier: 'semantic',
+    extensions: [BPMN_XML_EXTENSION, '.xml'],
+    mime: BPMN_XML_MIME,
+};
+/* ── Pure board helpers ───────────────────────────────────────────────── */
+/**
+ * The artefacts the exporter speaks about, picked out of a surface's elements
+ * and kept in the order they were given.
+ *
+ * Document order matters twice and both times for the same reason: `bpmnPoolOf`
+ * gives a centre inside two overlapping pools to the FIRST one, and the audit's
+ * `attribute()` does the same. Sorting here would make the export disagree with
+ * the badge the user can see.
+ */
+export function bpmnBoardFrom(elements) {
+    const pools = [];
+    const nodes = [];
+    const connectors = [];
+    for (const element of elements) {
+        if (element instanceof BpmnPoolElementModel)
+            pools.push(element);
+        else if (element instanceof BpmnNodeElementModel)
+            nodes.push(element);
+        else if (element instanceof ConnectorElementModel)
+            connectors.push(element);
+    }
+    return { pools, nodes, connectors };
+}
+/**
+ * A name a file system will accept, minus the extension.
+ *
+ * Every character a file system reserves becomes `-`, whitespace runs collapse,
+ * and the result is capped: `process` is a better download than one a browser
+ * silently refuses.
+ *
+ * The trailing `[. ]` trim is the Windows tail case and it is not decorative: a
+ * board called "Order to cash." would otherwise download as
+ * `Order to cash..bpmn`, and Windows strips trailing dots and spaces from a
+ * name anyway — so the extension is what would get eaten. Trimmed AFTER the
+ * cap, because the cap can create one.
+ */
+export function bpmnSafeFilename(raw) {
+    const safe = (raw ?? '')
+        .trim()
+        .replaceAll(/[\\/:*?"<>|]/g, '-')
+        .replaceAll(/\s+/g, ' ')
+        .trim()
+        .slice(0, 120)
+        .replace(/[. ]+$/, '');
+    return safe || 'process';
+}
+/* ── The capability ───────────────────────────────────────────────────── */
+/**
+ * The board as a BPMN 2.0 interchange document.
+ *
+ * A thin adapter and nothing else: it splits the surface into the three lists
+ * {@link exportBpmnXmlWithWarnings} takes, names the file, and passes the
+ * writer's losses straight through. There is no second door — `bpmn.exportXml`
+ * calls THIS, so the command and the registry cannot produce different bytes,
+ * different filenames or different warnings: there is nowhere for them to
+ * differ.
+ *
+ * `warnings` is omitted rather than empty when the board came out whole, so a
+ * caller can ask `if (result.warnings)` and mean it.
+ */
+const runBpmnXmlExport = (elements, context) => {
+    const name = bpmnSafeFilename(context.name);
+    const { text, warnings } = exportBpmnXmlWithWarnings(bpmnBoardFrom(elements), { name });
+    return {
+        text,
+        filename: `${name}${BPMN_XML_EXTENSION}`,
+        mime: BPMN_XML_MIME,
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+};
+/** `bpmn:bpmn:export` — the registry's first capability. */
+export const BPMN_XML_EXPORT = {
+    id: interchangeCapabilityId('bpmn', BPMN_XML_FORMAT.id, 'export'),
+    framework: 'bpmn',
+    format: BPMN_XML_FORMAT,
+    direction: 'export',
+    run: runBpmnXmlExport,
+};
+/**
+ * `bpmn:bpmn:import` — a `.bpmn` file as a board.
+ *
+ * A thin adapter over {@link importBpmnXml} and nothing else, which is the
+ * whole of what a capability is: the parser is a pure function of a string, so
+ * the registry entry has nothing to add to it and deliberately adds nothing.
+ * A reader that threw its arms around a surface here would be a reader
+ * labre-mcp could not call.
+ */
+export const BPMN_XML_IMPORT = {
+    id: interchangeCapabilityId('bpmn', BPMN_XML_FORMAT.id, 'import'),
+    framework: 'bpmn',
+    format: BPMN_XML_FORMAT,
+    direction: 'import',
+    run: importBpmnXml,
+};
+/* ── The visual tier ──────────────────────────────────────────────────── */
+/**
+ * SVG. **Visual** — the file carries a rendering, not a model.
+ *
+ * A separate format object from `BPMN_XML_FORMAT` and deliberately not a shared
+ * singleton with Wardley's: ADR 0012's unit is the TRIPLE, and the ADR
+ * explicitly rejects "one capability per format, with the framework inferred
+ * from the file" — a `.svg` is read by several frameworks and the inference is
+ * exactly the guess the ADR forbids everywhere else. The three constants come
+ * from the parser's own package so the two declarations cannot drift into
+ * disagreeing about the extension or the mime a picker filters on.
+ */
+export const BPMN_SVG_FORMAT = {
+    id: SVG_SKETCH_FORMAT_ID,
+    tier: 'visual',
+    extensions: [SVG_SKETCH_EXTENSION],
+    mime: SVG_SKETCH_MIME,
+};
+/**
+ * `bpmn:svg:import` — an SVG as a sketch, best effort.
+ *
+ * **The heuristics statement and the known failure modes this capability owes
+ * (ADR 0012, open question 2) are the module documentation of
+ * `packages/affine/blocks/surface/src/extensions/svg-sketch.ts`.** They are
+ * written once, there, because BPMN and Wardley wrap the SAME parser and
+ * therefore make the same guesses; a framework that ever wants narrower or
+ * wider recognition writes its own parser and its own paragraph beside it.
+ *
+ * What lands is a level-1 sketch (ADR 0007) — plain shapes, brush strokes and
+ * editable free text — that the author then PROMOTES into BPMN artefacts.
+ * Nothing here decides that a rounded rectangle in somebody's picture was a
+ * task, and no `interchange` payload is written, because a visual round-trip
+ * would be a re-render (P2).
+ */
+export const BPMN_SVG_IMPORT = {
+    id: interchangeCapabilityId('bpmn', BPMN_SVG_FORMAT.id, 'import'),
+    framework: 'bpmn',
+    format: BPMN_SVG_FORMAT,
+    direction: 'import',
+    run: parseSvgSketch,
+};
+/** Everything BPMN registers, in one list the view extension can hand over. */
+export const BPMN_INTERCHANGE = [
+    BPMN_XML_EXPORT,
+    BPMN_XML_IMPORT,
+    BPMN_SVG_IMPORT,
+];

package/dist/morph.d.ts

@@ -0,0 +1,61 @@
+import { type MorphSpec } from '@formicoidea/labre-core/blocks/surface';
+import { type BpmnNodeKind } from '@formicoidea/labre-core/model';
+/**
+ * What a BPMN artefact may BECOME — the declaration behind the "Change type"
+ * dropdown on a selected node's contextual toolbar.
+ *
+ * ## Families, and why they are a table
+ *
+ * A user task IS a task, said more precisely; a timer start IS a start event
+ * that names its trigger. Realising halfway through a draft that the rectangle
+ * should have been a user task is modelling, not a mistake — but the only way
+ * through it today is delete, re-draw, re-connect and re-type the label, which
+ * loses every sequence flow attached to the node.
+ *
+ * The six families below are DATA and nothing derives them. The role tree would
+ * have been the obvious source and it is the wrong one: `roleIsA` makes
+ * `bpmn:task` and `bpmn:sub-process` both `bpmn:activity`, so a derivation
+ * would offer "turn this task into a sub-process" — a swap between an atomic
+ * unit of work and a stand-in for a whole process, which is not the same
+ * artefact said more precisely but a different claim about the process. A
+ * reader has to accept the pair, and only a human knows which pairs a reader
+ * accepts.
+ *
+ * Each family is closed under "the same thing, more or less specific":
+ *
+ * - the three tasks — plain, and the two that say WHO performs the work;
+ * - the three starts and the three ends — plain, and the variants that say what
+ *   triggers the one and what the other does on the way out;
+ * - the two gateways — the same diamond, and the marker is the whole difference;
+ * - the two data artefacts — a data object dies with the process instance, a
+ *   data store outlives it, and both are the paperwork rather than the work;
+ * - the sub-process and the call activity — the two ways of standing for a
+ *   whole process, one defined inline and one defined elsewhere. They are each
+ *   other's neighbour and neither is a task.
+ *
+ * ## The two kinds with no family, deliberately
+ *
+ * `textAnnotation` and `group` are what the author drew ON the picture rather
+ * than IN it (BPMN 2.0.2 §10.4), and there is nothing either of them could
+ * become without ceasing to be commentary. They are in no family, so a
+ * selection holding one offers no menu at all — which is the same isolation
+ * `roles.ts` already gives them in the role tree.
+ */
+export declare const BPMN_MORPH_FAMILIES: readonly (readonly BpmnNodeKind[])[];
+/**
+ * BPMN's morph declaration, handed to the generic `morphToolbarConfig`.
+ *
+ * `propsOf` is the shipped creation builder minus `type` / `xywh` / `text`
+ * ({@link bpmnMorphProps}) and `clearOf` the keys the target does not write
+ * ({@link bpmnMorphClears}) — both live in `presets.ts`, beside the one
+ * description of what a BPMN node IS, precisely so that a morph and a creation
+ * can never disagree about what a `callActivity` looks like.
+ *
+ * That pair is the one place the FULL preset earns its keep on today's table:
+ * `subProcess` and `callActivity` differ only in `strokeWidth` (2 ⇄ 4), and the
+ * thick border is the whole distinction. Every other family here shares one
+ * preset across its members, so the rest of the patch is inert — kept anyway,
+ * because a family grows by DECLARATION and nobody would be prompted to check
+ * the presets on the day one gains a member that styles itself differently.
+ */
+export declare const BPMN_MORPH_SPEC: MorphSpec<BpmnNodeKind>;

package/dist/morph.js

@@ -0,0 +1,118 @@
+import { morphLabel, } from '@formicoidea/labre-core/blocks/surface';
+import { BpmnNodeElementModel } from '@formicoidea/labre-core/model';
+import { bpmnCommandIcons, bpmnCommands } from './commands.js';
+import { bpmnMorphClears, bpmnMorphProps } from './presets.js';
+import { BPMN_ROLE_OF_KIND } from './roles.js';
+/**
+ * What a BPMN artefact may BECOME — the declaration behind the "Change type"
+ * dropdown on a selected node's contextual toolbar.
+ *
+ * ## Families, and why they are a table
+ *
+ * A user task IS a task, said more precisely; a timer start IS a start event
+ * that names its trigger. Realising halfway through a draft that the rectangle
+ * should have been a user task is modelling, not a mistake — but the only way
+ * through it today is delete, re-draw, re-connect and re-type the label, which
+ * loses every sequence flow attached to the node.
+ *
+ * The six families below are DATA and nothing derives them. The role tree would
+ * have been the obvious source and it is the wrong one: `roleIsA` makes
+ * `bpmn:task` and `bpmn:sub-process` both `bpmn:activity`, so a derivation
+ * would offer "turn this task into a sub-process" — a swap between an atomic
+ * unit of work and a stand-in for a whole process, which is not the same
+ * artefact said more precisely but a different claim about the process. A
+ * reader has to accept the pair, and only a human knows which pairs a reader
+ * accepts.
+ *
+ * Each family is closed under "the same thing, more or less specific":
+ *
+ * - the three tasks — plain, and the two that say WHO performs the work;
+ * - the three starts and the three ends — plain, and the variants that say what
+ *   triggers the one and what the other does on the way out;
+ * - the two gateways — the same diamond, and the marker is the whole difference;
+ * - the two data artefacts — a data object dies with the process instance, a
+ *   data store outlives it, and both are the paperwork rather than the work;
+ * - the sub-process and the call activity — the two ways of standing for a
+ *   whole process, one defined inline and one defined elsewhere. They are each
+ *   other's neighbour and neither is a task.
+ *
+ * ## The two kinds with no family, deliberately
+ *
+ * `textAnnotation` and `group` are what the author drew ON the picture rather
+ * than IN it (BPMN 2.0.2 §10.4), and there is nothing either of them could
+ * become without ceasing to be commentary. They are in no family, so a
+ * selection holding one offers no menu at all — which is the same isolation
+ * `roles.ts` already gives them in the role tree.
+ */
+export const BPMN_MORPH_FAMILIES = [
+    // Declaration order is menu order, and it opens on the plain member of each
+    // family: the undecorated artefact is the honest first draft, and the variant
+    // is the refinement — the same call `commands.ts` makes about the senior row.
+    ['task', 'taskUser', 'taskService'],
+    ['startEvent', 'startEventMessage', 'startEventTimer'],
+    ['endEvent', 'endEventMessage', 'endEventTerminate'],
+    ['gatewayExclusive', 'gatewayParallel'],
+    ['dataObject', 'dataStore'],
+    ['subProcess', 'callActivity'],
+];
+/**
+ * The creation command that draws each kind, keyed BY that kind.
+ *
+ * Derived from `telemetry.element`, which is where the kind is already written
+ * down (`node:taskUser`) and is documented as a historical value that must not
+ * be renamed. Deriving rather than restating is what stops a second table of
+ * labels and icons drifting from the one the palette and the catalogue read: a
+ * kind whose command is renamed, re-iconed or re-worded changes here for free,
+ * and a kind with no creation command at all simply falls back to its own name.
+ */
+const NODE_COMMANDS = new Map(bpmnCommands.flatMap(command => {
+    const element = command.telemetry?.element;
+    return element?.startsWith('node:')
+        ? [[element.slice('node:'.length), command]]
+        : [];
+}));
+/**
+ * A kind's wording: the creation command's own key and English, so the dropdown
+ * says "User task" in whatever the host's catalogue says it in, and says
+ * exactly what the palette entry that draws one says.
+ */
+function labelOf(kind) {
+    const command = NODE_COMMANDS.get(kind);
+    return {
+        key: command?.labelKey,
+        fallback: command?.labelFallback ?? kind,
+    };
+}
+/** A kind's icon: the creation command's own, reused rather than redrawn. */
+function iconOf(kind) {
+    const iconKey = NODE_COMMANDS.get(kind)?.iconKey;
+    return ((iconKey && bpmnCommandIcons[iconKey]) || bpmnCommandIcons['bpmn.task']);
+}
+/**
+ * BPMN's morph declaration, handed to the generic `morphToolbarConfig`.
+ *
+ * `propsOf` is the shipped creation builder minus `type` / `xywh` / `text`
+ * ({@link bpmnMorphProps}) and `clearOf` the keys the target does not write
+ * ({@link bpmnMorphClears}) — both live in `presets.ts`, beside the one
+ * description of what a BPMN node IS, precisely so that a morph and a creation
+ * can never disagree about what a `callActivity` looks like.
+ *
+ * That pair is the one place the FULL preset earns its keep on today's table:
+ * `subProcess` and `callActivity` differ only in `strokeWidth` (2 ⇄ 4), and the
+ * thick border is the whole distinction. Every other family here shares one
+ * preset across its members, so the rest of the patch is inert — kept anyway,
+ * because a family grows by DECLARATION and nobody would be prompted to check
+ * the presets on the day one gains a member that styles itself differently.
+ */
+export const BPMN_MORPH_SPEC = {
+    framework: 'bpmn',
+    families: BPMN_MORPH_FAMILIES,
+    modelType: BpmnNodeElementModel,
+    kindOf: (model) => model instanceof BpmnNodeElementModel ? model.kind : undefined,
+    roleOf: kind => BPMN_ROLE_OF_KIND[kind],
+    propsOf: bpmnMorphProps,
+    clearOf: bpmnMorphClears,
+    labelOf,
+    iconOf,
+    label: morphLabel('com.labre.morph.toolbar.label', 'Change type'),
+};

package/dist/node/node-renderer.d.ts

@@ -1,14 +1,5 @@
 import { type ElementRenderer } from '@formicoidea/labre-core/blocks/surface';
 import { type BpmnNodeElementModel } from '@formicoidea/labre-core/model';
-/**
- * Renderer for a BPMN flow-object node. The shape body (ellipse / rounded rect
- * / diamond) is drawn by REUSING the native shape renderer — so stroke width,
- * colors, inner text and theme behave exactly like a native shape. Only
- * `gatewayExclusive` is decorated: an X drawn on top in the node's (editable)
- * stroke color. Events and task are plain native shapes.
- *
- * Mirrors the EDGY node renderer.
- */
 export declare const bpmnNode: ElementRenderer<BpmnNodeElementModel>;
 export declare const BpmnNodeRendererExtension: import("@formicoidea/labre-core/store").ExtensionType & {
     identifier: import("@formicoidea/labre-core/_pkgs/global/di").ServiceIdentifier<ElementRenderer<BpmnNodeElementModel>>;