@formicoidea/labre-framework-bpmn 0.32.0 → 0.33.0

package/dist/element-view.js

@@ -1,33 +1,270 @@
 import { EdgelessCRUDIdentifier } from '@formicoidea/labre-core/blocks/surface';
-import { GfxElementModelView, GfxViewInteractionExtension, } from '@formicoidea/labre-core/std/gfx';
+import { GfxElementModelView } from '@formicoidea/labre-core/std/gfx';
+import { bpmnLanesOf, renameBpmnLane } from './actions.js';
+import { POOL_LANE_MIN_HEIGHT } from './consts.js';
+import { bpmnLaneBoundaryAt, bpmnPoolBands, bpmnPoolTargetAt, } from './pool-hit.js';
 /**
- * View for a BPMN pool. A double-click edits the participant name in place
- * (single field — the whole pool is the hit target). Mirrors the inline label
- * editor used by the EDGY / Wardley backgrounds.
+ * View for a BPMN pool. Three direct gestures live here:
+ *
+ * - **dblclick in the pool's own title band** — the left margin strip the
+ *   participant name is written up — edits that name in place;
+ * - **dblclick in a lane's title band** edits THAT lane's name instead. A lane
+ *   name is not in the declaration's hit-test walk (`backgroundLabelHits`,
+ *   which Wardley uses): it is a function of the MODEL, not of the declaration,
+ *   so the box comes from `backgroundInstanceZoneBand` — the very rectangle the
+ *   renderer paints the name in, rather than a second set of metrics that would
+ *   one day disagree with it;
+ * - **drag on an internal lane boundary** moves the separator, taking from one
+ *   lane and giving to the other.
+ *
+ * Both renames are ZONED to their band (PO recette, 2026-08-26). The whole pool
+ * used to open the participant editor, which was right while a pool had one
+ * name; with a name per lane it would mean a double-click in the middle of the
+ * flow area renames the participant — neither of the two things the user could
+ * have meant, and the kind of write nobody notices until it is in a
+ * deliverable. A double-click on open canvas inside the pool now does nothing,
+ * and the `text` cursor over either band is what says where the names are.
+ *
+ * ## How the separator drag takes the gesture
+ *
+ * `GfxElementModelView.dispatch` reports a drag as handled whenever a handler
+ * is REGISTERED, without consulting what the handler returned, and the default
+ * tool stands down on that report. A permanently registered `dragstart` would
+ * therefore make a pool undraggable. So the drag handlers are ARMED — attached
+ * while the pointer is over a boundary of a selected pool, detached the moment
+ * it is not — and the pool moves normally everywhere else.
+ *
+ * Arming happens on `pointermove` AND on `pointerdown`, and neither is a hover
+ * requirement: a touch drag emits its first `pointermove` before the drag
+ * threshold is crossed (the move controller listens on the host, the drag
+ * controller on the document, so the host listener runs first), which is what
+ * makes the grab zone work with no hovering at all. The `ns-resize` cursor is a
+ * bonus for whoever has a mouse, never the affordance itself.
+ *
+ * ## The pool must be selected first
+ *
+ * Both the cursor and the grab are gated on the pool being selected. On an
+ * infinite canvas, dragging over an element means "move it"; silently turning a
+ * twelve-unit strip of an UNSELECTED pool into a resize handle would take that
+ * away from a user who never said they were working on this pool. One click
+ * first, and then the strip is live.
+ *
+ * ponytail: a ROTATED pool is not accounted for — the pointer is converted to
+ * element-local coordinates by subtraction, so every hit box here assumes an
+ * upright pool. Same reserve `backgroundAxisFacts` documents, for the same
+ * reason: nothing rotates a framework background today. Upgrade: rotate the
+ * local point by `-model.rotate` about the element centre, at the one function
+ * that has the element in hand (`_localPoint`), not a new declared field.
  */
 export class BpmnPoolView extends GfxElementModelView {
     constructor() {
         super(...arguments);
         this._nameEditor = null;
+        /** The boundary the pointer is over, and the handlers armed for it. */
+        this._armed = null;
+        /** Everything a separator drag needs, frozen at `dragstart`. */
+        this._drag = null;
     }
     static { this.type = 'bpmnPool'; }
     onCreated() {
         super.onCreated();
         this.on('dblclick', e => this._onDblClick(e));
+        this.on('pointermove', e => this._updateHover(e));
+        this.on('pointerdown', e => this._updateHover(e));
+        this.on('pointerleave', () => this._leave());
     }
     onDestroyed() {
         this._closeEditor();
+        this._leave();
         super.onDestroyed();
     }
+    /** Hand the cursor back on the way out; nothing here owns it for long. */
+    _leave() {
+        this._disarm();
+        if (!this._drag)
+            this.gfx.cursor$.value = 'default';
+    }
+    /* ── Lane geometry ─────────────────────────────────────────────────── */
+    /** The pointer, in element-local model units. */
+    _localPoint(e) {
+        const [mx, my] = this.gfx.viewport.toModelCoord(e.x, e.y);
+        const [ex, ey] = this.model.deserializedXYWH;
+        return [mx - ex, my - ey];
+    }
+    /**
+     * The boxes the gestures below aim at, all of them delegated to `pool-hit.ts`.
+     *
+     * That module is pure, so every answer here can be asserted without an
+     * editor, a viewport or a canvas; and it derives each box from
+     * `backgroundInstanceZones` / `backgroundInstanceZoneBand`, the same two
+     * functions the renderer paints from and the audit reports from. The view
+     * supplies the pointer and the zoom and nothing else.
+     */
+    _bands() {
+        return bpmnPoolBands(this.model);
+    }
+    _boundaryAt(local) {
+        return bpmnLaneBoundaryAt(this.model, local);
+    }
+    /** Which name this point aims at, if any — lane strip first, see `pool-hit`. */
+    _targetAt(local) {
+        return bpmnPoolTargetAt(this.model, local, this.gfx.viewport.zoom);
+    }
+    get _editable() {
+        return !this.gfx.std.store.readonly && !this.model.isLocked();
+    }
+    /* ── Hover: what this point would do ───────────────────────────────── */
+    /**
+     * One pass over the pointer, deciding both the cursor and whether a
+     * separator drag is armed.
+     *
+     * The order is the order the gestures win in. A separator sits INSIDE a lane
+     * title band at every lane boundary, so the two overlap and something has to
+     * give: the separator takes it, because it is a twelve-unit strip the user
+     * has to aim at deliberately, while the title band is the whole leading edge
+     * and has plenty left over. It is also already gated on the pool being
+     * selected, so on an unselected pool the band wins uncontested.
+     */
+    _updateHover(e) {
+        const local = this._localPoint(e);
+        const selected = this.gfx.selection.selectedIds.includes(this.model.id);
+        if (this._editable && selected) {
+            const index = this._boundaryAt(local);
+            if (index !== null) {
+                // Reasserted on every move rather than only on arrival: the cursor is a
+                // signal shared with the resize handles and the tools, and whoever set
+                // it last wins — so the one that is still true says so again.
+                this.gfx.cursor$.value = 'ns-resize';
+                if (this._armed?.index !== index) {
+                    this._disarm();
+                    this._armed = {
+                        index,
+                        disposers: [
+                            this.on('dragstart', evt => this._onDragStart(evt)),
+                            this.on('dragmove', evt => this._onDragMove(evt)),
+                            this.on('dragend', () => this._onDragEnd()),
+                        ],
+                    };
+                }
+                return;
+            }
+        }
+        this._disarm();
+        // A title band announces itself, selected or not: finding out that a name
+        // can be changed should not cost a click first. Gated on `_editable` all
+        // the same — an I-beam over a locked pool would promise an editor that
+        // refuses to open, which is the sort of small lie the recette is against.
+        const overTitle = this._editable && this._targetAt(local) !== null;
+        this.gfx.cursor$.value = overTitle ? 'text' : 'default';
+    }
+    _disarm() {
+        // Never mid-gesture: the pointer leaves the boundary as soon as the drag
+        // starts moving, and disarming there would drop the drag on its first step.
+        if (this._drag)
+            return;
+        if (!this._armed)
+            return;
+        this._armed.disposers.forEach(dispose => dispose());
+        this._armed = null;
+    }
+    _onDragStart(_) {
+        const index = this._armed?.index;
+        const geometry = this._bands();
+        if (index === undefined || !geometry || !this._editable)
+            return;
+        const lanes = bpmnLanesOf(this.model);
+        if (!lanes[index - 1] || !lanes[index])
+            return;
+        const total = lanes.reduce((sum, lane) => sum + lane.size, 0);
+        if (!(total > 0))
+            return;
+        this._drag = {
+            index,
+            lanes: lanes.map(lane => ({ ...lane })),
+            total,
+            plotHeight: geometry.plot.height,
+            // The floor is a HEIGHT the user can see, so it is stated in the model
+            // units of a pool at its reference height and converted to a weight
+            // against this pool's own total — a pool stretched to twice the height
+            // keeps the same visible floor, which is the point of weights.
+            minWeight: (POOL_LANE_MIN_HEIGHT / geometry.plot.height) * total,
+        };
+        // Local writes until the release: the intermediate weights repaint the
+        // canvas but never reach the document, so the whole drag is ONE undo step.
+        this.model.stash('lanes');
+    }
+    _onDragMove(e) {
+        const drag = this._drag;
+        if (!drag)
+            return;
+        // The travel SINCE the drag started, in view pixels (`e.delta` is the step
+        // since the last move, which is not the same thing), converted to model
+        // units. Always recomputed from the FROZEN pair rather than nudged: a nudge
+        // would accumulate the clamp and drift away from the pointer.
+        const dy = (e.y - e.start.y) / (this.gfx.viewport.zoom || 1);
+        const perUnit = drag.total / drag.plotHeight;
+        const above = drag.lanes[drag.index - 1];
+        const below = drag.lanes[drag.index];
+        const pair = above.size + below.size;
+        // The pair's total is invariant: the separator takes from one and gives to
+        // the other, so no lane the user is not touching changes size.
+        const wanted = above.size + dy * perUnit;
+        const floor = Math.min(drag.minWeight, pair / 2);
+        const nextAbove = Math.max(floor, Math.min(pair - floor, wanted));
+        const next = drag.lanes.map((lane, i) => i === drag.index - 1
+            ? { ...lane, size: nextAbove }
+            : i === drag.index
+                ? { ...lane, size: pair - nextAbove }
+                : lane);
+        this.model.lanes = next;
+    }
+    _onDragEnd() {
+        const drag = this._drag;
+        this._drag = null;
+        if (!drag)
+            return;
+        // Before the commit, not after: `pop` writes straight into the Y.Map, and
+        // without a boundary here a separator moved within half a second of the
+        // previous edit would be undone together with it.
+        this.gfx.std.store.captureSync();
+        this.model.pop('lanes');
+        this._disarm();
+    }
+    /* ── In-place naming ───────────────────────────────────────────────── */
+    /**
+     * A double-click renames whatever TITLE BAND it landed in, and nothing
+     * otherwise (PO recette, 2026-08-26).
+     *
+     * The whole pool used to open the participant editor. That was right while a
+     * pool had one name; now that every lane carries one it would mean a
+     * double-click in the middle of the flow area renames the participant — not
+     * one of the things the user could have meant, and the kind of write nobody
+     * notices until it is in a deliverable. A double-click on open canvas inside
+     * the pool now does nothing, which is the honest answer.
+     */
     _onDblClick(e) {
-        if (this.model.isLocked())
+        if (!this._editable)
+            return;
+        const target = this._targetAt(this._localPoint(e));
+        if (target === null)
+            return;
+        if (target.kind === 'lane') {
+            const { index } = target;
+            const lane = bpmnLanesOf(this.model)[index];
+            this._openEditor(e, lane?.name ?? '', value => renameBpmnLane(this.gfx.std, this.model, index, value));
             return;
-        this._openEditor(e);
+        }
+        this._openEditor(e, String(this.model.name ?? ''), value => {
+            this.gfx.std.store.captureSync();
+            this.gfx.std
+                .get(EdgelessCRUDIdentifier)
+                .updateElement(this.model.id, { name: value });
+        });
     }
-    _openEditor(e) {
+    _openEditor(e, initial, commit) {
         this._closeEditor();
         const input = document.createElement('input');
-        input.value = String(this.model.name ?? '');
+        input.value = initial;
         Object.assign(input.style, {
             position: 'fixed',
             left: `${e.raw.clientX}px`,
@@ -51,28 +288,25 @@ export class BpmnPoolView extends GfxElementModelView {
         this.gfx.selection.set({ elements: [this.model.id], editing: true });
         input.focus();
         input.select();
-        const commit = () => {
+        const onCommit = () => {
             if (this._nameEditor !== input)
                 return;
             const value = input.value;
             this._closeEditor();
-            this.gfx.std.store.captureSync();
-            this.gfx.std
-                .get(EdgelessCRUDIdentifier)
-                .updateElement(this.model.id, { name: value });
+            commit(value);
         };
         input.addEventListener('keydown', ev => {
             ev.stopPropagation();
             if (ev.key === 'Enter') {
                 ev.preventDefault();
-                commit();
+                onCommit();
             }
             else if (ev.key === 'Escape') {
                 ev.preventDefault();
                 this._closeEditor();
             }
         });
-        input.addEventListener('blur', commit);
+        input.addEventListener('blur', onCommit);
     }
     _closeEditor() {
         if (!this._nameEditor)
@@ -85,18 +319,3 @@ export class BpmnPoolView extends GfxElementModelView {
         }
     }
 }
-/**
- * Resize gating: the resize handles are hidden unless `model.resizeEnabled` is
- * true (toggled from the toolbar). Moving / selecting stays available.
- */
-export const BpmnPoolInteraction = GfxViewInteractionExtension(BpmnPoolView.type, {
-    handleResize({ model }) {
-        return {
-            beforeResize({ set }) {
-                if (!model.resizeEnabled) {
-                    set({ allowedHandlers: [] });
-                }
-            },
-        };
-    },
-});

package/dist/export.d.ts

@@ -0,0 +1,277 @@
+import type { BpmnNodeElementModel, BpmnNodeKind, BpmnPoolElementModel, ConnectorElementModel } from '@formicoidea/labre-core/model';
+/**
+ * The board, as a BPMN 2.0 interchange document (clause 15) — semantic model
+ * plus BPMN DI, in one `definitions` element.
+ *
+ * ## Pure by construction
+ *
+ * Element models in, string out. No `BlockStdScope`, no surface, no DOM, no
+ * clock and no randomness — the same discipline `facts.ts` holds itself to, and
+ * for the same three reasons: a host can call it, a test can call it with plain
+ * stubs, and the same board always serializes to the same bytes. The command
+ * that downloads the file is the only thing that knows what a canvas is.
+ *
+ * ## What it says, and what it refuses to say
+ *
+ * The export speaks the author's STATEMENTS and nothing else. A connector
+ * carrying no BPMN role relates nothing — `docs/adr/0010` is explicit that the
+ * role is the statement — so it is not a sequence flow that happens to be
+ * untyped, it is not a flow at all, and it is absent. A plain rectangle drawn
+ * beside a pool is likewise not an unnamed task. The alternative — guessing —
+ * would put words in an architect's mouth in a file they are about to hand to
+ * an execution engine.
+ *
+ * ## Conformance target
+ *
+ * The **Descriptive** sub-class of BPMN 2.0 (spec Table 2.1), which is exactly
+ * the vocabulary the pack draws: the seventeen artefacts map onto the
+ * seventeen-odd element names that table lists, and nothing here needs the
+ * executable half of the metamodel. Clause 15.1 explicitly licenses a partial
+ * model — implementers "disregard missing attributes marked required" — which
+ * is what lets a picture drawn for humans round-trip through bpmn.io without
+ * inventing an `ioSpecification` nobody asked for.
+ */
+/**
+ * The four namespaces an interchange file is written in, with the prefixes the
+ * spec's own schema uses (`bpmndi`, `di`, `dc`; §12.2.4 and Annex B).
+ *
+ * Prefixes are arbitrary and URIs are not — bpmn.io writes the same two DD
+ * namespaces as `omgdi` / `omgdc` — so the URIs are what is pinned by the tests
+ * and the prefixes merely have to be consistent with themselves. The MODEL
+ * namespace is given the explicit `bpmn` prefix rather than made the default,
+ * because a reader of the file should never have to work out which of two
+ * unprefixed vocabularies an element belongs to.
+ *
+ * The stale `.../BPMNDI/1.0.0` that appears in the spec's own clause 15.3.1
+ * example is a documented erratum and is NOT what the normative schema says.
+ */
+export declare const BPMN_NS: {
+    readonly model: "http://www.omg.org/spec/BPMN/20100524/MODEL";
+    readonly bpmndi: "http://www.omg.org/spec/BPMN/20100524/DI";
+    readonly di: "http://www.omg.org/spec/DD/20100524/DI";
+    readonly dc: "http://www.omg.org/spec/DD/20100524/DC";
+};
+/**
+ * The four declarations this library writes, as they appear on `definitions` —
+ * the PAIR, prefix and URI together, and the pair is the point.
+ *
+ * A reader carries a file's namespace declarations because a carried fragment
+ * is stored with the prefixes the file spelled it in, and a `camunda:property`
+ * or a `bpmn2:boundaryEvent` means nothing under a declaration nobody wrote.
+ * What it must NOT carry is a declaration this writer is going to make anyway,
+ * or the payload gains four permanent entries, every Labre file reports four
+ * things carried, and the "a file we wrote comes back with an empty middle
+ * column" property — the no-slow-leak property — stops being true.
+ *
+ * Keyed by the attribute NAME rather than by the URI, because the prefix is
+ * exactly what differs: bpmn.io writes the model namespace as `bpmn2:` and this
+ * library writes it as `bpmn:`, and a fragment carrying `bpmn2:` is unreadable
+ * unless `xmlns:bpmn2` comes back with it. Same URI, different prefix,
+ * different fate — which a set of URIs cannot express.
+ */
+export declare const BPMN_OWN_DECLARATIONS: Readonly<Record<string, string>>;
+/**
+ * The interchange format's id — the key under which foreign matter from a
+ * `.bpmn` rides on an element (`interchange.bpmn`, ADR 0012 D2), and the middle
+ * term of both capability ids.
+ *
+ * Declared here, in the module both directions already depend on, so that the
+ * writer, the reader and the registry entry cannot disagree about which key
+ * they are talking about.
+ */
+export declare const BPMN_FORMAT_ID = "bpmn";
+/**
+ * Which slot of `process` an artefact serializes into.
+ *
+ * Not decoration: the spec's `tProcess` sequence is `laneSet* → flowElement* →
+ * artifact*` in that order, and a `textAnnotation` written before a `task` is a
+ * document a validating parser rejects. It also decides what a LANE may point
+ * at — `flowNodeRef` is an IDREF to a flow NODE, and a data reference is a flow
+ * element that is not one, so a data object sitting in a lane is simply not
+ * referenced by it.
+ */
+type BpmnXmlSlot = 'flowNode' | 'data' | 'artifact';
+export interface BpmnXmlMapping {
+    /** The semantic element name, in the MODEL namespace. */
+    element: string;
+    slot: BpmnXmlSlot;
+    /** The child that says what TRIGGERS the event, for the four variants. */
+    eventDefinition?: 'messageEventDefinition' | 'timerEventDefinition' | 'terminateEventDefinition';
+}
+/**
+ * The whole notation, kind by kind — the table this module is really about.
+ *
+ * `Record<BpmnNodeKind, …>` and therefore COMPILE-TOTAL: a kind added to the
+ * pack without a BPMN element name to serialize it as fails the build here,
+ * which is the only place that failure is cheap. A kind that reached a
+ * document and had no mapping would be an artefact the author drew, saved, and
+ * then silently lost on export.
+ *
+ * Three of the seventeen do not map one-for-one and the reasons are the spec's:
+ *
+ * - the four TRIGGERED events are `startEvent` / `endEvent` carrying an event
+ *   definition child, never elements of their own — "message start event" is a
+ *   start event with a `messageEventDefinition` in it (§10.4.2);
+ * - a data object serializes as `dataObjectReference`, because DI attaches to
+ *   the REFERENCE and not to the `dataObject` it points at (§10.4.1, and the
+ *   spec's own rule that "Data Object Reference cannot specify item
+ *   definitions, and Data Objects cannot specify states"). The `dataObject`
+ *   itself is emitted alongside it;
+ * - a `group` carries no `name` at all. Its visible label is the `value` of the
+ *   `categoryValue` it points at, which is a ROOT element of the document — the
+ *   one place in this file where drawing a box round three tasks costs two
+ *   extra elements somewhere else entirely (§10.4, Table 8.30).
+ */
+export declare const BPMN_XML_OF_KIND: Record<BpmnNodeKind, BpmnXmlMapping>;
+/**
+ * Character DATA — the three characters that would otherwise start markup.
+ *
+ * A newline, a tab and a carriage return are left exactly as they are, which is
+ * what makes `<bpmn:text>` carry a multi-line annotation faithfully: inside an
+ * element, whitespace is content.
+ */
+export declare function escapeText(value: string): string;
+/**
+ * An attribute VALUE, which needs strictly more than character data does.
+ *
+ * The quotes are the obvious half. The other half is the one that loses data
+ * silently: XML 1.0 §3.3.3 makes every conformant parser replace a literal
+ * `#xA`, `#xD` or `#x9` in an attribute value with a SPACE before anyone sees
+ * it — attribute-value normalization, and it is not optional. Only a character
+ * reference survives it.
+ *
+ * That matters here because a multi-line label is ordinary on this canvas (it
+ * is how a task fits in its box) and `name` is where nearly all of them go:
+ * every flow node, the participant, the lane, the flows, and
+ * `categoryValue/@value`. Written raw, a two-line task name comes back as one
+ * line, with no warning and no way for the author to tell. Written as `&#10;`
+ * it comes back as it went in.
+ */
+export declare function escapeAttr(value: string): string;
+/**
+ * A surface id, as an XML NCName.
+ *
+ * `id` is `xsd:ID` throughout BPMN, which means NCName and means
+ * DOCUMENT-unique — a `BPMNShape` may not carry the id of the `task` it
+ * describes. Surface ids are nanoid-shaped: they routinely open on a digit and
+ * may carry a `-`, both of which a validating parser refuses on an `xsd:ID`.
+ *
+ * So: every disallowed character becomes `_`, and an id that does not open on a
+ * letter or `_` is prefixed with one. The transformation is lossy on purpose —
+ * two distinct surface ids can collapse onto the same NCName — which is what
+ * {@link IdMinter} is for.
+ */
+export declare function toNcName(raw: string): string;
+/** Whether a string is already an NCName, and can therefore be given back. */
+export declare function isNcName(value: string): boolean;
+/**
+ * `.bpmn`'s scope vocabulary — where a carried fragment came off, and therefore
+ * where this writer has to put it back (ADR 0012, D2 as amended in #157).
+ *
+ * Declared HERE, in the module both directions already depend on, for the same
+ * reason {@link BPMN_FORMAT_ID} is: the reader files a fragment under a scope
+ * and the writer looks it up under one, and a table written twice is a table
+ * that drifts. `import.ts` re-exports it.
+ *
+ * One Labre element stands for several source elements: a pool is a
+ * `participant` AND its `process`, plus a `laneSet`, every `lane`, the
+ * `BPMNShape` that draws it, and — on the first pool of a document — the
+ * `collaboration` and `definitions` themselves. Everything they carry lands in
+ * ONE payload, so what came off which is recorded, or two lanes with the same
+ * foreign attribute leave one value in a persisted field and a report that says
+ * two.
+ *
+ * A scope is either a source element's **id, verbatim** — every carried flow
+ * node, every lane, every carried root element — or one of the `@` keys below,
+ * for the parts of the document that have no id worth naming or whose identity
+ * is their relation to this element. `@` is not an XML NameStartChar, so no id
+ * in a conformant file can ever collide with one.
+ *
+ * The rule for a fragment is always the same: **the scope is the element it was
+ * a child of**. For an attribute it is the element that carried the attribute;
+ * for a `di` fragment, what that fragment draws.
+ */
+export declare const BPMN_SCOPE: {
+    /** The element this payload rides on: the participant, the flow node, the flow. */
+    readonly self: "@self";
+    /** Its `BPMNShape` or `BPMNEdge`. */
+    readonly shape: "@shape";
+    /** The `process` behind a participant — the pool's other half. */
+    readonly process: "@process";
+    /** The pool's `laneSet`. */
+    readonly laneSet: "@laneSet";
+    /** The `collaboration`, whose residue rides on the first pool (D6). */
+    readonly collaboration: "@collaboration";
+    /** `definitions` itself: its foreign attributes, its declarations, its roots. */
+    readonly definitions: "@definitions";
+};
+/**
+ * The board to serialize — everything on the surface, split by what it is.
+ *
+ * The whole board and not a selection: a BPMN document is a process, and half a
+ * process is not a smaller process. The pool whose toolbar launched the export
+ * decides the FILENAME and nothing else.
+ */
+export interface BpmnExportBoard {
+    /** In document order — which is the tie-break `bpmnPoolOf` breaks on. */
+    pools: readonly BpmnPoolElementModel[];
+    nodes: readonly BpmnNodeElementModel[];
+    connectors: readonly ConnectorElementModel[];
+}
+export interface BpmnExportOptions {
+    /** Names the `collaboration` / lone `process` and the `BPMNDiagram`. */
+    name?: string;
+}
+/**
+ * The document, plus what writing it could not say.
+ *
+ * Three things the board can hold have no honest place in a `.bpmn` file, and
+ * until now each of them was documented in a code comment and silent to the
+ * person who clicked Export. A warning is one line, in the user's words, and it
+ * names the fix rather than the mechanism. Nothing here is an error: the file
+ * is valid and the export succeeded — these are the sentences the format
+ * refused to carry.
+ */
+export interface BpmnExportOutcome {
+    text: string;
+    /** Empty when the board came out whole, which is the usual case. */
+    warnings: string[];
+}
+/**
+ * Serialize a board as a BPMN 2.0 XML interchange document.
+ *
+ * ## The shape of the document, and what decides it
+ *
+ * One `definitions`, always. Then:
+ *
+ * - **at least one pool** — a `collaboration` holding one `participant` per
+ *   pool, one `process` per pool, and the message flows (which are the
+ *   collaboration's, never a process's). Things drawn OUTSIDE every pool split
+ *   in two: ARTIFACTS (annotation, group, and the associations that tie them to
+ *   anything) become children of the collaboration itself, where
+ *   `tCollaboration` allows them and where bpmn-js draws them; FLOW OBJECTS get
+ *   ONE extra participant-less process, and only if there are any. See
+ *   {@link COLLABORATION} for what the live recette found out about the
+ *   difference, and the note on the orphan process for what it still cannot fix;
+ * - **no pool at all** — a single `process` and no collaboration, which is what
+ *   a process drawn without swimlanes IS. The `BPMNPlane` then points at that
+ *   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.
+ */
+export declare function exportBpmnXml(board: BpmnExportBoard, options?: BpmnExportOptions): string;
+/**
+ * The same serialization, with the loss channel attached — see
+ * {@link BpmnExportOutcome}.
+ *
+ * {@link exportBpmnXml} is the thin wrapper over it, kept because a caller that
+ * only wants the bytes should not have to reach past a report to get them, and
+ * because #149's forty-six tests and the live integration spec pin that
+ * signature. The interchange capability calls THIS one.
+ */
+export declare function exportBpmnXmlWithWarnings(board: BpmnExportBoard, options?: BpmnExportOptions): BpmnExportOutcome;
+export {};