@formicoidea/labre-framework-bpmn 0.32.0 → 0.33.0

package/dist/actions.js

@@ -1,21 +1,20 @@
-import { DefaultTool } from '@formicoidea/labre-core/blocks/surface';
+import { DefaultTool, EdgelessCRUDIdentifier, generateElementId, materializeInterchangeImport, reportInterchangeImport, runInterchangeImportFile, } from '@formicoidea/labre-core/blocks/surface';
 import { ConnectorTool } from '@formicoidea/labre-core/gfx/connector';
-import { ConnectorMode, FontFamily, PointStyle, ShapeStyle, StrokeStyle, TextFitMode, } from '@formicoidea/labre-core/model';
-import { EditPropsStore } from '@formicoidea/labre-core/shared/services';
+import { BpmnPoolElementModel, ConnectorMode, PointStyle, StrokeStyle, } from '@formicoidea/labre-core/model';
+import { NotificationProvider, translateKey, } from '@formicoidea/labre-core/shared/services';
+import { downloadBlob } from '@formicoidea/labre-core/shared/utils';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
 import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
-import { END_WIDTH, EVENT_END, EVENT_START, INNER_FONT_SIZE, NEUTRAL_STROKE, NODE_FILL, NODE_LABEL, NODE_SIZE, NODE_STROKE_WIDTH, SEQUENCE_STROKE, SEQUENCE_WIDTH, START_WIDTH, TASK_RADIUS, } from './consts.js';
-/** Per-kind native shape + accent presets (style C). */
-const NODE_PRESETS = {
-    startEvent: { shapeType: 'ellipse', stroke: EVENT_START, width: START_WIDTH },
-    endEvent: { shapeType: 'ellipse', stroke: EVENT_END, width: END_WIDTH },
-    task: { shapeType: 'rect', stroke: NEUTRAL_STROKE, width: NODE_STROKE_WIDTH },
-    gatewayExclusive: {
-        shapeType: 'diamond',
-        stroke: NEUTRAL_STROKE,
-        width: NODE_STROKE_WIDTH,
-    },
-};
+import { ASSOCIATION_STROKE, ASSOCIATION_WIDTH, MESSAGE_STROKE, MESSAGE_WIDTH, NODE_LABEL, 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 { BPMN_ROLE } from './roles.js';
+/**
+ * Standalone creation/activation actions for the BPMN toolbox — lifted out of
+ * `toolbar/bpmn-menu.ts` by PF3 so the menu becomes a pure renderer over the
+ * command registry. Telemetry is emitted once, by `runCommand`.
+ */
 const gfxOf = (std) => std.get(GfxControllerIdentifier);
 function finish(gfx, id) {
     gfx.doc.captureSync();
@@ -31,28 +30,15 @@ export function createBpmnNode(std, kind) {
         return;
     const { w, h } = NODE_SIZE[kind];
     const { centerX: cx, centerY: cy } = gfx.viewport;
-    const preset = NODE_PRESETS[kind];
-    const id = surface.addElement({
-        type: 'bpmnNode',
-        kind,
-        shapeType: preset.shapeType,
-        filled: true,
-        fillColor: NODE_FILL,
-        strokeColor: preset.stroke,
-        strokeWidth: preset.width,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        radius: kind === 'task' ? TASK_RADIUS : 0,
-        text: NODE_LABEL[kind] || undefined,
-        color: NEUTRAL_STROKE,
-        fontFamily: FontFamily.Inter,
-        fontSize: INNER_FONT_SIZE,
-        textAlign: 'center',
-        // BPMN symbols have normative sizes: a long label overflows rather
-        // than deforming the node
-        textFitMode: TextFitMode.Overflow,
+    // What a node IS lives in one place (`./presets.ts`), because the importer
+    // creates the same artefacts out of a `.bpmn` file and the two must not
+    // drift: a task read from a file and a task drawn here are one element type
+    // in the document, down to the stroke width. The gesture owns the BOX and
+    // nothing else.
+    const id = surface.addElement(bpmnNodeProps(kind, {
         xywh: new Bound(cx - w / 2, cy - h / 2, w, h).serialize(),
-    });
+        text: NODE_LABEL[kind] || undefined,
+    }));
     finish(gfx, id);
 }
 /** Create a pool (background container) centred on the viewport. */
@@ -66,6 +52,9 @@ export function createBpmnPool(std) {
     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(),
     });
     finish(gfx, id);
@@ -76,14 +65,403 @@ export function createBpmnPool(std) {
  * one node to another (endpoints attach to centers).
  */
 export function activateBpmnSequenceFlow(std) {
-    std.get(EditPropsStore).recordLastProps('connector', {
+    gfxOf(std).tool.setTool(ConnectorTool, {
         mode: ConnectorMode.Orthogonal,
-        stroke: SEQUENCE_STROKE,
-        strokeStyle: StrokeStyle.Solid,
-        strokeWidth: SEQUENCE_WIDTH,
-        frontEndpointStyle: PointStyle.None,
-        rearEndpointStyle: PointStyle.Triangle,
+        // A TYPED edge (`docs/adr/0010`): the arrow the user is about to draw says
+        // "is followed by", so its source is what happens first. The tool carries
+        // the role so the connector is born with it rather than acquiring one
+        // afterwards.
+        role: BPMN_ROLE.sequenceFlow,
+        // The flow's look rides on the activation, never through the last-props
+        // store: the plain connector tool must keep the user's own style (#144 M1).
+        style: {
+            stroke: SEQUENCE_STROKE,
+            strokeStyle: StrokeStyle.Solid,
+            strokeWidth: SEQUENCE_WIDTH,
+            frontEndpointStyle: PointStyle.None,
+            rearEndpointStyle: PointStyle.Triangle,
+        },
     });
-    gfxOf(std).tool.setTool(ConnectorTool, { mode: ConnectorMode.Orthogonal });
     // Keep the palette open (native sub-menu behaviour).
 }
+/**
+ * Arm the native connector tool, pre-styled for a BPMN message flow:
+ * orthogonal, DASHED, an open circle where the message leaves and an open
+ * arrowhead where it lands.
+ *
+ * ## The two endpoint styles, and why these two
+ *
+ * The spec's message flow starts on a small hollow circle and ends on a hollow
+ * (line-drawn) arrowhead — never the solid triangle the sequence flow uses,
+ * which is the whole visual difference between "then this happens" and "and
+ * this is what I told them". `PointStyle` offers `Circle` and `Arrow`, and they
+ * are exactly those two shapes: `Arrow` is drawn as an unfilled V
+ * (`renderRoundedPolygon(…, false)`), against `Triangle`'s filled one. The only
+ * deviation is that `Circle` is painted with the connector's `fillColor` rather
+ * than left transparent — the shape, the size and the position are the spec's.
+ */
+export function activateBpmnMessageFlow(std) {
+    gfxOf(std).tool.setTool(ConnectorTool, {
+        mode: ConnectorMode.Orthogonal,
+        // A TYPED edge (`docs/adr/0010`), and the role its vocabulary already
+        // declared with the verb "sends a message to": the source is the
+        // participant that sends, the target the one that receives.
+        role: BPMN_ROLE.messageFlow,
+        // The flow's look rides on the activation, never through the last-props
+        // store: the plain connector tool must keep the user's own style (#144 M1).
+        style: {
+            stroke: MESSAGE_STROKE,
+            strokeStyle: StrokeStyle.Dash,
+            strokeWidth: MESSAGE_WIDTH,
+            frontEndpointStyle: PointStyle.Circle,
+            rearEndpointStyle: PointStyle.Arrow,
+        },
+    });
+    // Keep the palette open (native sub-menu behaviour).
+}
+/**
+ * Arm the native connector tool, pre-styled for a BPMN association: dashed, and
+ * with NO endpoint marker at either end.
+ *
+ * The missing arrowheads are the point, not an omission. An association names
+ * no relation — `bpmn:association` is the one edge role in this vocabulary
+ * declared without a `direction` block — so "this note is about that task"
+ * reads identically from either end, and an arrowhead would be the picture
+ * claiming a direction the role explicitly refuses to have. See the role's own
+ * doc comment in `./roles.ts`.
+ *
+ * On the dash (there is no dotted stroke to ask for) see
+ * {@link ASSOCIATION_STROKE}'s neighbours in `./consts.ts`.
+ */
+export function activateBpmnAssociation(std) {
+    gfxOf(std).tool.setTool(ConnectorTool, {
+        mode: ConnectorMode.Orthogonal,
+        role: BPMN_ROLE.association,
+        // The association's look rides on the activation, never through the
+        // last-props store: the plain connector tool must keep the user's own
+        // style (#144 M1).
+        style: {
+            stroke: ASSOCIATION_STROKE,
+            strokeStyle: StrokeStyle.Dash,
+            strokeWidth: ASSOCIATION_WIDTH,
+            frontEndpointStyle: PointStyle.None,
+            rearEndpointStyle: PointStyle.None,
+        },
+    });
+    // Keep the palette open (native sub-menu behaviour).
+}
+/* ── Lanes (couloirs) ─────────────────────────────────────────────────── */
+/**
+ * The lanes a pool carries, as an array that is safe to read.
+ *
+ * The value comes out of a Y.Map, so it is whatever a peer wrote: a client that
+ * got it wrong must not break the gesture on this one. Same defensive read the
+ * validation engine does on `validationExceptions`, for the same reason.
+ */
+export function bpmnLanesOf(model) {
+    const stored = model.lanes;
+    return Array.isArray(stored) ? stored : [];
+}
+/**
+ * The pools a lane gesture acts on: every pool of the current selection that is
+ * not locked.
+ *
+ * EVERY one, not the single one — `some`, not `every`, in the same spirit as
+ * the typed-edge inversion (`docs/adr/0010` M3): lassoing two pools used to be
+ * a way to lose an affordance, and a gesture that says what it did on each of
+ * them beats an entry that vanishes. With one pool selected — the ordinary
+ * case, and the only one the toolbar offers — it is exactly "the selected pool".
+ */
+export function bpmnPoolsForLaneEdit(std) {
+    if (std.store.readonly)
+        return [];
+    return gfxOf(std)
+        .selection.selectedElements.filter((model) => model instanceof BpmnPoolElementModel)
+        .filter(model => !model.isLocked());
+}
+/**
+ * Write a pool's lane list back, or REMOVE the prop when there is none left.
+ *
+ * The second half is what keeps the "nothing is written until the first lane"
+ * promise reversible: assigning `undefined` through the accessor would leave
+ * the key in the Y.Map holding an undefined value — invisible through the
+ * getter, but synced to every peer and shipped in every snapshot. A pool whose
+ * last lane is removed goes back to its pre-lane bytes.
+ */
+function writeLanes(std, model, lanes) {
+    if (lanes.length === 0) {
+        model.clearField('lanes');
+        return;
+    }
+    std.get(EdgelessCRUDIdentifier).updateElement(model.id, {
+        lanes: [...lanes],
+    });
+}
+/**
+ * Append a lane to every selected pool.
+ *
+ * ## One lane, not two
+ *
+ * Adding the FIRST lane creates ONE lane, covering the whole pool. Seeding two
+ * would invent a subdivision the user did not ask for and then make them delete
+ * half of it. One lane is the honest reading of "add a lane": the pool now has
+ * a lane, it happens to be all of it, and the second click gives them the
+ * second one.
+ *
+ * Since the lane title band (PO recette, 2026-08-26) that first click is also
+ * VISIBLE: a named strip appears down the leading edge of a pool that had none.
+ * Before it, a single lane was indistinguishable from no lane at all, and the
+ * gesture looked broken until the second click.
+ *
+ * ## `Lane N` is DOCUMENT DATA, not vocabulary
+ *
+ * The default name is a plain persisted string, exactly like the pool's own
+ * `'Pool'` default: it is written into the document by this action and is the
+ * user's to rewrite from that moment on. It is deliberately NOT a `labelKey`
+ * through the translation seam — a host that ships a French catalogue must not
+ * silently retitle a lane an author named, and a name that changed language
+ * when the reader's locale did would be a document that says different things
+ * to different people. `N` is the count AFTER this lane, so the first is
+ * `Lane 1`.
+ */
+export function addBpmnLane(std) {
+    const pools = bpmnPoolsForLaneEdit(std);
+    if (pools.length === 0)
+        return;
+    // Before the writes: `Store.transact` is not an undo boundary, and one
+    // capture for the whole gesture is what makes several pools take their lane
+    // in a single undo step.
+    std.store.captureSync();
+    for (const model of pools) {
+        const lanes = bpmnLanesOf(model);
+        // The new lane takes an equal share: the average of what is already there
+        // is the weight that leaves every existing lane the same size relative to
+        // its neighbours, and gives the newcomer the room a typical one has. `1`
+        // for the first, where there is no average and the unit is arbitrary.
+        const size = lanes.length
+            ? lanes.reduce((sum, lane) => sum + lane.size, 0) / lanes.length
+            : 1;
+        writeLanes(std, model, [
+            ...lanes,
+            { id: generateElementId(), name: `Lane ${lanes.length + 1}`, size },
+        ]);
+    }
+}
+/**
+ * Remove the LAST lane of every selected pool.
+ *
+ * The last one and not the selected one, because a lane is not selectable: it
+ * is a slice of the pool's plot, painted by the background primitive, with no
+ * element of its own. Removing from the end is the gesture that undoes the one
+ * that added it.
+ *
+ * ## Nothing moves
+ *
+ * Elements sitting in the removed lane do NOT move. Containment here is
+ * geometric — a task is "in" a lane because its centre falls in that rectangle,
+ * which is how the audit reports it — so the lane below simply grows over them
+ * and they are in that one now. Nothing on the canvas jumps under the user's
+ * hand, and the sequence flow they drew still lands where they drew it.
+ */
+export function removeBpmnLane(std) {
+    const pools = bpmnPoolsForLaneEdit(std);
+    if (pools.length === 0)
+        return;
+    const withLanes = pools.filter(model => bpmnLanesOf(model).length > 0);
+    if (withLanes.length === 0)
+        return;
+    std.store.captureSync();
+    for (const model of withLanes) {
+        writeLanes(std, model, bpmnLanesOf(model).slice(0, -1));
+    }
+}
+/* ── Export (BPMN 2.0 XML) ────────────────────────────────────────────── */
+/**
+ * The pools of the current selection, WITHOUT the two filters a lane gesture
+ * applies.
+ *
+ * `bpmnPoolsForLaneEdit` refuses a read-only document and a locked pool because
+ * it is about to write to them. An export writes nothing: it reads the board
+ * and hands the reader a file. A process published read-only, or a pool an
+ * author locked precisely because it is finished, is exactly the board somebody
+ * wants to take to bpmn.io — refusing it there would be a filter copied for the
+ * shape of it rather than for the reason.
+ */
+export function bpmnPoolsSelected(std) {
+    return gfxOf(std).selection.selectedElements.filter((model) => model instanceof BpmnPoolElementModel);
+}
+/**
+ * Everything on the surface the exporter speaks about, in document order.
+ *
+ * The half that needs an editor, and only that half: reading the surface. The
+ * picking is {@link bpmnBoardFrom}, which the interchange capability calls with
+ * the same elements and no `std` at all (`docs/adr/0012`, P3).
+ */
+export function bpmnBoardOf(std) {
+    return bpmnBoardFrom(gfxOf(std).surface?.elementModels ?? []);
+}
+/**
+ * What the downloaded file is called, minus the extension.
+ *
+ * The document's own title first — a board is what the file is OF — then the
+ * name of the pool whose toolbar launched the export, then a last resort. Which
+ * of the three it is, is the only thing this function decides; making the
+ * answer safe to write to disk is {@link bpmnSafeFilename}, so the command and
+ * the interchange capability cannot name the same board differently.
+ */
+export function bpmnExportFilename(std) {
+    const title = std.store.workspace.meta.getDocMeta(std.store.id)?.title;
+    const pool = bpmnPoolsSelected(std)[0]?.name;
+    return bpmnSafeFilename(title || pool);
+}
+/**
+ * Serialize the whole board as BPMN 2.0 XML and hand it to the browser.
+ *
+ * Three steps, and only the first and the last know what an editor is: read the
+ * surface, run the DECLARED capability (`docs/adr/0012`), download what it
+ * produced. The middle step is not re-implemented here — the document, the
+ * filename and the content type all come out of `BPMN_XML_EXPORT.run`, so the
+ * command and the registry cannot describe the same board differently. There is
+ * one door; the registry is the label on it.
+ *
+ * A plain import rather than a DI lookup: the capability is a pure function and
+ * a value, resolving it through the container would buy nothing here, and P3 is
+ * explicit that the registry is the editor's view of these functions, not a
+ * gate in front of them.
+ */
+export function exportBpmnXmlFile(std) {
+    const elements = gfxOf(std).surface?.elementModels ?? [];
+    const { text, filename, mime, warnings } = BPMN_XML_EXPORT.run(elements, {
+        name: bpmnExportFilename(std),
+    });
+    // The charset is the browser's business, not the format's: `mime` is what
+    // `.bpmn` IS, and this is how a blob is told to carry it.
+    downloadBlob(new Blob([text], { type: `${mime};charset=utf-8` }), filename);
+    // The `warnings` channel, spent. The writer has been populating it since
+    // #149 and the command dropped it on the floor — a #159 review nit, and the
+    // one thing that made "an export loses things too, and the user who clicked
+    // Export is the one person entitled to be told" false in the only place a
+    // user stands. A warning is never an error: the file downloaded, and it is
+    // valid; what it could not say is what this names.
+    if (!warnings || warnings.length === 0)
+        return;
+    notifyBpmn(std, {
+        title: translateKey(std, EXPORT_WARNINGS_KEY, EXPORT_WARNINGS_FALLBACK),
+        message: warnings.join('\n'),
+        accent: 'warning',
+    });
+}
+/**
+ * The one wording this file still owns: what a WRITER could not say.
+ *
+ * The import's wordings moved to the pipeline that writes them
+ * (`affine-block-surface`, `extensions/interchange-import.ts`) — one set of
+ * keys for every format, with the format's own name composed into them, so a
+ * host translates "file imported" once instead of once per format. This one
+ * stays because no other format's writer speaks through it.
+ */
+const EXPORT_WARNINGS_KEY = 'com.labre.commands.bpmn.exportXml.warnings';
+const EXPORT_WARNINGS_FALLBACK = 'What this export could not write down';
+/**
+ * The notification seam, or silence.
+ *
+ * `getOptional`, like every other call site in the library: the host injects a
+ * `NotificationService` (labreapp does, the standalone playground does not), and
+ * a framework that assumed one would be a framework the playground cannot run.
+ * Nothing here decides that an export said nothing because nobody was
+ * listening — the file downloaded either way.
+ */
+function notifyBpmn(std, options) {
+    std.getOptional(NotificationProvider)?.notify({
+        title: options.title,
+        message: options.message,
+        accent: options.accent,
+        // Long enough to read a paragraph of remarks, and still self-dismissing:
+        // an import report is not a modal, and a toast the user has to close is a
+        // toast that interrupts the next thing they were doing.
+        duration: 8000,
+    });
+}
+/* ── Import (BPMN 2.0 XML) ────────────────────────────────────────────── */
+/**
+ * Write an imported board onto the surface, and give back the ids it minted.
+ *
+ * BPMN's name for {@link materializeInterchangeImport}, which is where the two
+ * passes live and are documented (`docs/adr/0012`, D3). Nothing in them was
+ * ever about BPMN except the payload key the source ids ride under, so the
+ * function moved to the surface package when the second format asked for it and
+ * this name stayed: it is what the chromium round trip calls, and a test that
+ * proves the shipped command has to keep calling the shipped function.
+ */
+export function materializeBpmnImport(std, elements) {
+    return materializeInterchangeImport(std, BPMN_FORMAT_ID, elements);
+}
+/**
+ * Say what the import did — the summary, and the remarks.
+ *
+ * BPMN's name for {@link reportInterchangeImport}, which is where the argument
+ * for a toast plus a console table lives (ADR 0012's open question 4, v1). The
+ * format is a word in the sentence now rather than a wording per format, so
+ * what a user reads is unchanged: the counts, and `BPMN` before the version the
+ * reader actually read.
+ */
+export function reportBpmnImport(std, report) {
+    reportInterchangeImport(std, BPMN_XML_FORMAT, report);
+}
+/**
+ * Read a `.bpmn` file the user picks, draw it, and say what it cost.
+ *
+ * The whole gesture is {@link runInterchangeImportFile}, over the capability
+ * BPMN declares: pick the file, run the DECLARED reader, write what it
+ * returned, fit the drawing, report. `BPMN_XML_IMPORT.run` is the same function
+ * labre-mcp calls, so the command and the registry cannot read the same file
+ * differently — one door, and the registry is the label on it. The picker's
+ * filter comes off `BPMN_XML_FORMAT` rather than off the shared `FileTypes`
+ * table, which is why `.xml` is declared there: half the tools in the wild
+ * write a process under the generic extension, and what the file actually IS is
+ * decided by the reader, which throws on anything that is not a BPMN
+ * `<definitions>`.
+ */
+export async function importBpmnXmlFile(std) {
+    await runInterchangeImportFile(std, BPMN_XML_IMPORT);
+}
+/**
+ * Read an SVG the user picks as a SKETCH, and say what it cost.
+ *
+ * The same four steps as the `.bpmn` import, over a different declared
+ * capability — which is the whole point of the seam: a second format costs a
+ * declaration and a command, not a pipeline. What differs is the PROMISE, and
+ * the promise is made by the command's own label and description before the
+ * picker ever opens (`docs/adr/0012`, P2): recognition, best effort, no
+ * round-trip, and a level-1 sketch the author then promotes.
+ */
+export async function importBpmnSvgFile(std) {
+    await runInterchangeImportFile(std, BPMN_SVG_IMPORT);
+}
+/**
+ * Rename one lane of one pool. Called by the in-place editor
+ * (`element-view.ts`); exported so a unit test can assert the write without an
+ * editor around it.
+ *
+ * An empty name REMOVES the key rather than storing `''`: the renderer already
+ * treats both as "no name", and one of the two would be a second way to say the
+ * same thing that only the bytes can tell apart.
+ */
+export function renameBpmnLane(std, model, index, name) {
+    const lanes = bpmnLanesOf(model);
+    const lane = lanes[index];
+    if (!lane)
+        return;
+    const trimmed = name.trim();
+    if ((lane.name ?? '') === trimmed)
+        return;
+    const next = lanes.map((entry, i) => i === index
+        ? {
+            id: entry.id,
+            ...(trimmed ? { name: trimmed } : {}),
+            size: entry.size,
+        }
+        : entry);
+    std.store.captureSync();
+    writeLanes(std, model, next);
+}

package/dist/background.d.ts

@@ -0,0 +1,2 @@
+import type { FrameworkBackgroundDef } from '@formicoidea/labre-core/blocks/surface';
+export declare const BPMN_POOL_BACKGROUND: FrameworkBackgroundDef;

package/dist/background.js

@@ -0,0 +1,158 @@
+import { POOL_BAND_FILL, POOL_BAND_WIDTH, POOL_CARD_FILL, POOL_CORNER_RADIUS, POOL_FONT_FAMILY, POOL_FRAME_COLOR, POOL_FRAME_WIDTH, POOL_LANE_BAND_WIDTH, POOL_LANE_NAME_FONT_SIZE, POOL_NAME_COLOR, POOL_NAME_FONT_SIZE, POOL_REF_HEIGHT, POOL_REF_WIDTH, } from './consts.js';
+import { BPMN_ROLE } from './roles.js';
+/**
+ * The BPMN pool, DECLARED (the `FrameworkBackgroundDef` primitive).
+ *
+ * This file is the whole of what makes a pool look like a pool. There is no
+ * BPMN drawing code left: the primitive paints this declaration, and would
+ * paint any other framework's the same way — what used to be ninety lines of
+ * `ctx.fillRect` / `ctx.arcTo` / `ctx.rotate` is now data a reviewer can read.
+ *
+ * Nothing here changes the DOCUMENT. The persisted element type is still
+ * `bpmnPool` and its props are untouched — `name`, `resizeEnabled`, `rotate`,
+ * `xywh` — they are simply named by the declaration instead of being read by
+ * hand-written drawing code. A pool authored before this file existed opens
+ * with the same frame, the same band and the same participant name.
+ *
+ * ## No frame of reference
+ *
+ * A pool declares no axis and no zone, and that is deliberate: a pool is a
+ * PARTICIPANT, not a chart. Nothing about where a task sits inside the lane
+ * means anything — left-to-right is the sequence flow's business, and the flow
+ * says so with an arrow. Declaring a time axis here would invent a semantic
+ * BPMN puts on the connectors, and then judge people against it.
+ *
+ * ## The band
+ *
+ * The left margin IS the name band: `margin.left` is both the room the flow
+ * area gives up and the width of the strip the participant name is written in
+ * (see `BackgroundSideBandDef`).
+ *
+ * ## The lanes
+ *
+ * A lane (couloir) is NOT a second element type, and it is not a band either:
+ * it is a slice of THIS pool's plot, so it is declared as an instance partition
+ * (`BackgroundInstanceZonesDef`) read off the pool's own `lanes` prop. How many
+ * there are, what they are called and how the height is shared between them is
+ * a property of this pool; that a pool CAN be sliced that way is the property
+ * of BPMN declared here.
+ *
+ * Which is also why the lanes are not zones: a `zones` entry is part of the
+ * framework and identical on every element of it, and no two pools have the
+ * same lanes.
+ *
+ * Each lane wears its own title band inside the pool's — a narrower strip, no
+ * fill, one divider, the name turned on its side, exactly as BPMN 2.0 draws it.
+ * The strip is CHROME inside the lane and not a smaller lane: a task dropped on
+ * a lane's title band is in that lane, because in BPMN the band belongs to it.
+ */
+/** The colour code: every colour named once, never repeated as a hex. */
+const PALETTE = {
+    card: POOL_CARD_FILL,
+    frame: POOL_FRAME_COLOR,
+    band: POOL_BAND_FILL,
+    name: POOL_NAME_COLOR,
+};
+export const BPMN_POOL_BACKGROUND = {
+    type: 'bpmnPool',
+    // The pool is a first-class role: rules frame against `bpmn:pool`, never
+    // against the `bpmnPool` element type. Same vocabulary the creation site
+    // stamps (`actions.ts`) and the templates ship, named once in `roles.ts`.
+    role: BPMN_ROLE.pool,
+    geometry: {
+        width: POOL_REF_WIDTH,
+        height: POOL_REF_HEIGHT,
+        // A lane is stretched in one direction all the time — long and thin as the
+        // process grows sideways, tall only when it has to hold more. Locking the
+        // proportion would fight the hand on every drag.
+        lockAspectRatio: false,
+        resizable: true,
+        margin: { top: 0, right: 0, bottom: 0, left: POOL_BAND_WIDTH },
+    },
+    instanceZones: {
+        prop: 'lanes',
+        // Horizontal bands, top to bottom in array order: a lane runs ALONG the
+        // flow, and the flow runs left to right.
+        stack: 'y',
+        // A namespace, so a lane the user calls `early` can never shadow a
+        // framework zone of that name. A pool declares no zones today; the
+        // separation is what makes that stay true if it ever does.
+        idPrefix: 'lane',
+        // The same stroke as the band divider — the two lines meet at the band's
+        // inner edge, and a lane separator that did not match would read as a
+        // different KIND of line rather than the same frame continued.
+        divider: { color: '@frame', width: POOL_FRAME_WIDTH },
+        label: {
+            // The BAND placement: a title strip at the lane's leading edge with the
+            // name turned on its side, which is how BPMN 2.0 draws a lane and how
+            // bpmn.io, Camunda and Visio all render one. The corner placement this
+            // used to declare put the name across the lane's top-left instead; the
+            // PO's visual recette (2026-08-26) settled it against the corner on
+            // notation rather than taste — a reader who knows BPMN reads a strip as a
+            // lane title and a floating corner word as a note.
+            //
+            // No fill: the strip is the participant band's subordinate, and a second
+            // grey gutter beside it would leave the flow area looking inset twice.
+            band: {
+                width: POOL_LANE_BAND_WIDTH,
+                // The frame's own line again, as the band divider is: every rule on a
+                // pool is the same stroke, so the lanes read as the frame continued.
+                divider: { color: '@frame', width: POOL_FRAME_WIDTH },
+            },
+            style: {
+                size: POOL_LANE_NAME_FONT_SIZE,
+                color: '@name',
+                weight: 600,
+            },
+        },
+    },
+    chrome: {
+        fontFamily: POOL_FONT_FAMILY,
+        palette: PALETTE,
+        // An opaque white card, like every other framework background (PO recette,
+        // 26/08/2026). The hand-written renderer left the pool transparent, on the
+        // reasoning that a lane is a frame you drop nodes INTO; the review settled
+        // it the other way, and settled it on identity: a pool is a map background,
+        // so it paints a card, and a board where one framework's backdrop is
+        // see-through and every other one is not reads as a bug.
+        //
+        // The consequence is the standard framework-background behaviour, not a
+        // pool quirk: dropping a pool over strokes already on the canvas covers
+        // them, exactly as dropping a Wardley map over them does. The user's answer
+        // is the same in both cases — send the background to the back.
+        surface: {
+            fill: '@card',
+            border: {
+                color: '@frame',
+                width: POOL_FRAME_WIDTH,
+                radius: POOL_CORNER_RADIUS,
+            },
+        },
+        sideBands: [
+            {
+                side: 'left',
+                fill: '@band',
+                divider: { color: '@frame', width: POOL_FRAME_WIDTH },
+                label: {
+                    id: 'name',
+                    // The user's own words, and only those: a participant is named by
+                    // whoever draws the process, so there is no vocabulary to fall back
+                    // to and no `labelKey` to declare.
+                    prop: 'name',
+                    // `x: 0` is the inner edge of the band; half a band width back from
+                    // it is the middle of the strip.
+                    anchor: { x: 0, y: 0.5, dx: -POOL_BAND_WIDTH / 2 },
+                    style: {
+                        size: POOL_NAME_FONT_SIZE,
+                        weight: 600,
+                        color: '@name',
+                        // Centred ACROSS the band, not sitting on a baseline inside it.
+                        baseline: 'middle',
+                    },
+                    // Read bottom-to-top, as the spec draws a vertical pool name.
+                    vertical: true,
+                },
+            },
+        ],
+    },
+};