@formicoidea/labre-framework-bpmn 0.40.0 → 0.41.0

package/dist/actions.d.ts

@@ -79,16 +79,16 @@ export declare function bpmnPoolsForLaneEdit(std: BlockStdScope): BpmnPoolElemen
  * 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
+ * ## `Lane N` is a SEED, resolved once at placement
  *
  * 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`.
+ * user's to rewrite from that moment on. Since the i18n pass (#278) it goes
+ * through the translation seam exactly as `nodeLabelKey` does for a node's
+ * caption — resolved HERE, once, so a lane added in a translated host starts
+ * in that language, and never re-resolved afterwards: a lane the author has
+ * since renamed is document content, and nothing here revisits it. `{{n}}` is
+ * the count AFTER this lane, so the first is `Lane 1`.
  */
 export declare function addBpmnLane(std: BlockStdScope): void;
 /**

package/dist/actions.js

@@ -5,8 +5,8 @@ import { NotificationProvider, translateKey, } from '@formicoidea/labre-core/sha
 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 { ASSOCIATION_STROKE, ASSOCIATION_WIDTH, MESSAGE_STROKE, MESSAGE_WIDTH, NODE_LABEL, nodeLabelKey, NODE_SIZE, SEQUENCE_STROKE, SEQUENCE_WIDTH, } from './consts.js';
-import { BPMN_FORMAT_ID } from './export.js';
+import { ASSOCIATION_STROKE, ASSOCIATION_WIDTH, LANE_NAME_FALLBACK, LANE_NAME_KEY, MESSAGE_STROKE, MESSAGE_WIDTH, NODE_LABEL, nodeLabelKey, NODE_SIZE, POOL_NAME_FALLBACK, POOL_NAME_KEY, SEQUENCE_STROKE, SEQUENCE_WIDTH, } from './consts.js';
+import { BPMN_FORMAT_ID, exportBpmnXmlWithWarnings, } from './export.js';
 import { BPMN_SVG_IMPORT, BPMN_XML_EXPORT, BPMN_XML_FORMAT, BPMN_XML_IMPORT, bpmnBoardFrom, bpmnSafeFilename, } from './interchange.js';
 import { bpmnNodeProps, bpmnPoolProps } from './presets.js';
 import { BPMN_ROLE } from './roles.js';
@@ -60,7 +60,16 @@ export function createBpmnPool(std) {
     // and for the same reason: the shipped cards build their participants from it
     // too, so a pool laid out by a template and one dropped from the toolbox
     // cannot say different things. The gesture owns the BOX and nothing else.
-    const id = surface.addElement(bpmnPoolProps({ xywh: new Bound(cx - w / 2, cy - h / 2, w, h).serialize() }));
+    //
+    // The NAME is the one exception, and it is written HERE rather than left to
+    // the model's default (`BpmnPoolElementModel.name = 'Pool'`, a red-zone
+    // field: a document created before this key existed keeps its literal
+    // 'Pool' verbatim). Resolved at placement and never again — content from
+    // the moment it lands, exactly like a node's caption.
+    const id = surface.addElement(bpmnPoolProps({
+        xywh: new Bound(cx - w / 2, cy - h / 2, w, h).serialize(),
+        name: translateKey(std, POOL_NAME_KEY, POOL_NAME_FALLBACK),
+    }));
     finish(gfx, id);
 }
 /**
@@ -217,16 +226,16 @@ function writeLanes(std, model, lanes) {
  * 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
+ * ## `Lane N` is a SEED, resolved once at placement
  *
  * 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`.
+ * user's to rewrite from that moment on. Since the i18n pass (#278) it goes
+ * through the translation seam exactly as `nodeLabelKey` does for a node's
+ * caption — resolved HERE, once, so a lane added in a translated host starts
+ * in that language, and never re-resolved afterwards: a lane the author has
+ * since renamed is document content, and nothing here revisits it. `{{n}}` is
+ * the count AFTER this lane, so the first is `Lane 1`.
  */
 export function addBpmnLane(std) {
     const pools = bpmnPoolsForLaneEdit(std);
@@ -245,9 +254,14 @@ export function addBpmnLane(std) {
         const size = lanes.length
             ? lanes.reduce((sum, lane) => sum + lane.size, 0) / lanes.length
             : 1;
+        const n = lanes.length + 1;
         writeLanes(std, model, [
             ...lanes,
-            { id: generateElementId(), name: `Lane ${lanes.length + 1}`, size },
+            {
+                id: generateElementId(),
+                name: translateKey(std, LANE_NAME_KEY, LANE_NAME_FALLBACK, { n }),
+                size,
+            },
         ]);
     }
 }
@@ -335,9 +349,8 @@ export function bpmnExportFilename(std) {
  */
 export function exportBpmnXmlFile(std) {
     const elements = gfxOf(std).surface?.elementModels ?? [];
-    const { text, filename, mime, warnings } = BPMN_XML_EXPORT.run(elements, {
-        name: bpmnExportFilename(std),
-    });
+    const name = bpmnExportFilename(std);
+    const { text, filename, mime } = BPMN_XML_EXPORT.run(elements, { name });
     // 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);
@@ -347,11 +360,25 @@ export function exportBpmnXmlFile(std) {
     // 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)
+    //
+    // Read straight from the PURE exporter rather than through
+    // `BPMN_XML_EXPORT.run` above: the interchange capability's `warnings` is
+    // `readonly string[]` (a seam shared with every other format, resolved to
+    // its English fallback with no `std` to ask), while the STRUCTURED
+    // `BpmnExportWarning[]` — key, fallback, params — is what `translateKey`
+    // needs. Calling the exporter a second time costs nothing beyond CPU (it is
+    // pure and deterministic on the same `elements`/`name`), and keeps the
+    // downloaded bytes on the one door `BPMN_XML_EXPORT.run` already is.
+    const { warnings } = exportBpmnXmlWithWarnings(bpmnBoardFrom(elements), {
+        name,
+    });
+    if (warnings.length === 0)
         return;
     notifyBpmn(std, {
         title: translateKey(std, EXPORT_WARNINGS_KEY, EXPORT_WARNINGS_FALLBACK),
-        message: warnings.join('\n'),
+        message: warnings
+            .map(w => translateKey(std, w.key, w.fallback, w.params))
+            .join('\n'),
         accent: 'warning',
     });
 }

package/dist/consts.d.ts

@@ -135,6 +135,26 @@ export declare const NODE_LABEL: Record<BpmnNodeKind, string>;
  * no word to translate, and BPMN puts an event's name outside its glyph anyway.
  */
 export declare const nodeLabelKey: (kind: BpmnNodeKind) => string;
+/**
+ * The pool's own default name, at creation — a plain seed like {@link
+ * NODE_LABEL}, and never restated: `packages/affine/model/src/elements/bpmn/pool.ts`
+ * still defaults `name` to the English literal `'Pool'` (a document created
+ * before this key existed, or without a host catalogue, keeps that exact
+ * text), but `createBpmnPool` writes the resolved value explicitly so a pool
+ * dropped in a translated host starts in that language.
+ *
+ * "Pool" is the PO's glossary term for BPMN: the French proposal IS the
+ * English word.
+ */
+export declare const POOL_NAME_KEY = "com.labre.bpmn.seed.pool";
+export declare const POOL_NAME_FALLBACK = "Pool";
+/**
+ * A fresh lane's name — `Lane 1`, `Lane 2`… — resolved AT PLACEMENT
+ * (`addBpmnLane`) like every other seed here. `{{n}}` is the count AFTER the
+ * lane being added, so the first is `Lane 1`.
+ */
+export declare const LANE_NAME_KEY = "com.labre.bpmn.seed.lane";
+export declare const LANE_NAME_FALLBACK = "Lane {{n}}";
 /**
  * Pool (background container) defaults — read by the `BPMN_POOL_BACKGROUND`
  * declaration (`background.ts`), which is the only thing that draws a pool.

package/dist/consts.js

@@ -172,6 +172,26 @@ export const NODE_LABEL = {
  * no word to translate, and BPMN puts an event's name outside its glyph anyway.
  */
 export const nodeLabelKey = (kind) => `com.labre.bpmn.seed.${kind}`;
+/**
+ * The pool's own default name, at creation — a plain seed like {@link
+ * NODE_LABEL}, and never restated: `packages/affine/model/src/elements/bpmn/pool.ts`
+ * still defaults `name` to the English literal `'Pool'` (a document created
+ * before this key existed, or without a host catalogue, keeps that exact
+ * text), but `createBpmnPool` writes the resolved value explicitly so a pool
+ * dropped in a translated host starts in that language.
+ *
+ * "Pool" is the PO's glossary term for BPMN: the French proposal IS the
+ * English word.
+ */
+export const POOL_NAME_KEY = 'com.labre.bpmn.seed.pool';
+export const POOL_NAME_FALLBACK = 'Pool';
+/**
+ * A fresh lane's name — `Lane 1`, `Lane 2`… — resolved AT PLACEMENT
+ * (`addBpmnLane`) like every other seed here. `{{n}}` is the count AFTER the
+ * lane being added, so the first is `Lane 1`.
+ */
+export const LANE_NAME_KEY = 'com.labre.bpmn.seed.lane';
+export const LANE_NAME_FALLBACK = 'Lane {{n}}';
 /**
  * Pool (background container) defaults — read by the `BPMN_POOL_BACKGROUND`
  * declaration (`background.ts`), which is the only thing that draws a pool.

package/dist/export.d.ts

@@ -222,6 +222,23 @@ export interface BpmnExportOptions {
     /** Names the `collaboration` / lone `process` and the `BPMNDiagram`. */
     name?: string;
 }
+/**
+ * One warning, KEYED rather than a resolved string — see
+ * {@link BpmnExportOutcome}. `exportBpmnXmlWithWarnings` is pure and has no
+ * `std` to ask a host's catalogue, so it hands back the key, the English
+ * fallback (with `{{name}}` placeholders) and the params to fill them; the
+ * caller that DOES have `std` (`exportBpmnXmlFile`, `actions.ts`) is the one
+ * that calls `translateKey`.
+ */
+export interface BpmnExportWarning {
+    key: string;
+    /** The English default, `{{name}}` placeholders included. */
+    fallback: string;
+    /** Values for the fallback's placeholders — a count, a list of names. */
+    params?: Record<string, string | number>;
+}
+/** All nine, for `translations.ts`'s manifest contribution. */
+export declare const BPMN_EXPORT_WARNING_KEYS: readonly (readonly [string, string])[];
 /**
  * The document, plus what writing it could not say.
  *
@@ -235,7 +252,7 @@ export interface BpmnExportOptions {
 export interface BpmnExportOutcome {
     text: string;
     /** Empty when the board came out whole, which is the usual case. */
-    warnings: string[];
+    warnings: BpmnExportWarning[];
 }
 /**
  * Serialize a board as a BPMN 2.0 XML interchange document.

package/dist/export.js

@@ -763,6 +763,67 @@ class IdMinter {
         return unique;
     }
 }
+/**
+ * The nine export-warning keys, each paired with its English fallback
+ * (`{{name}}` placeholders included) — declared ONCE, here, and read both by
+ * the `if` blocks below (which add the live `params`) and by
+ * `translations.ts`'s manifest (which needs the pair with no board to run
+ * against).
+ */
+// Each fallback below is ONE unbroken literal rather than the `+`-joined
+// pieces an earlier draft used: `manifest.unit.spec.ts`'s drift check reads a
+// key/fallback PAIR as two adjacent literals in one argument list, and a
+// concatenation left it seeing only the first piece — a drift the check
+// itself then (correctly) flagged. A long line is the trade for a fallback
+// the check can actually confirm against the manifest.
+const UNDRAWN_ARTEFACTS_WARNING = [
+    'com.labre.bpmn.export.warning.undrawn',
+    '{{count}} artefact(s) are drawn outside every pool. They are in the file, but most BPMN tools will not draw them: only a pool has a shape to hold them. Draw them inside a pool to make them visible.',
+];
+const DROPPED_MESSAGE_FLOWS_WARNING = [
+    'com.labre.bpmn.export.warning.dropped-message-flows',
+    '{{count}} message flow(s) were left out: a message flow runs between participants, and this board has no pool. Draw the pools it runs between, or say "is followed by" instead.',
+];
+const SUBSTITUTED_IDS_WARNING = [
+    'com.labre.bpmn.export.warning.substituted-ids',
+    '{{count}} element(s) imported from a BPMN file could not keep their original id: it was already taken in this file. A new id was written instead; nothing else changed.',
+];
+const DISPLACED_SHAPES_WARNING = [
+    'com.labre.bpmn.export.warning.displaced-shapes',
+    '{{count}} shape(s) imported from a BPMN file are kept exactly as the file drew them, and the rest of this drawing has moved since. They will open beside the process rather than inside it. Nothing was lost: they are in the file, at the position the original gave them.',
+];
+const CONTRADICTING_DECLARATIONS_WARNING = [
+    'com.labre.bpmn.export.warning.contradicting-declarations',
+    "This board came from a BPMN file that used {{names}} for something other than what BPMN means by them. Labre writes its own, so the file's declarations were left out rather than allowed to redefine the diagram's own namespaces. They are still in the document. Anything the file wrote under those prefixes is still in the export and will now be read under Labre's meaning of them, which is not the meaning the original had.",
+];
+const DISAGREEING_DECLARATIONS_WARNING = [
+    'com.labre.bpmn.export.warning.disagreeing-declarations',
+    "Two pools on this board disagree about {{names}}: they came from BPMN files that gave the same name two different values. The last was written and the other left out, so matter carried from the first file is now read under the second's meaning. Both are still in the document.",
+];
+const CONFLICTING_IDS_WARNING = [
+    'com.labre.bpmn.export.warning.conflicting-ids',
+    '{{count}} element(s) imported from a BPMN file could not be written back: {{names}} name(s) an id another imported element had already claimed, and a BPMN id must be unique across a document. The first was kept. The other(s) are still in the document; they are not in this file.',
+];
+const REFUSED_ATTRIBUTE_NAMES_WARNING = [
+    'com.labre.bpmn.export.warning.refused-attribute-names',
+    '{{count}} carried attribute(s) could not be written back, because their name(s) are not a valid XML name. They are still in the document. This is a sign the payload was edited by something other than a BPMN import.',
+];
+const UNWRITABLE_EDGES_WARNING = [
+    'com.labre.bpmn.export.warning.unwritable-edges',
+    '{{count}} arrow(s) were left out: BPMN requires both ends of a flow to be named, and they have an end that is loose or attached to something that is not a BPMN artefact.',
+];
+/** All nine, for `translations.ts`'s manifest contribution. */
+export const BPMN_EXPORT_WARNING_KEYS = [
+    UNDRAWN_ARTEFACTS_WARNING,
+    DROPPED_MESSAGE_FLOWS_WARNING,
+    SUBSTITUTED_IDS_WARNING,
+    DISPLACED_SHAPES_WARNING,
+    CONTRADICTING_DECLARATIONS_WARNING,
+    DISAGREEING_DECLARATIONS_WARNING,
+    CONFLICTING_IDS_WARNING,
+    REFUSED_ATTRIBUTE_NAMES_WARNING,
+    UNWRITABLE_EDGES_WARNING,
+];
 /* ── The plan ─────────────────────────────────────────────────────────── */
 /**
  * Which element an artefact is written INSIDE.
@@ -1465,6 +1526,14 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
         ...slot(document, 'relationship'),
     ]);
     /* ── What the format refused to carry ────────────────────────────── */
+    //
+    // Each warning is a KEY plus its English fallback and params — see
+    // `BpmnExportWarning`. This function stays `std`-free (like every other
+    // pure exporter in the pack), so it cannot ask a host's catalogue itself;
+    // `exportBpmnXmlFile` (`actions.ts`) resolves every one of these through
+    // `translateKey` before showing them. The fallback is deliberately NEUTRAL
+    // on number ("{{count}} element(s)") rather than branching singular/plural
+    // English by hand: pluralisation is the host's, off `count`.
     const warnings = [];
     // Flow objects drawn beside the pools. They are in the file and correct for
     // any tool that reads the MODEL, and a collaboration plane has no shape to
@@ -1478,18 +1547,12 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
         ? planned.filter(node => node.scope === orphanProcess).length
         : 0;
     if (undrawn > 0) {
-        warnings.push(`${undrawn} ${undrawn === 1 ? 'artefact is' : 'artefacts are'} drawn ` +
-            `outside every pool. ${undrawn === 1 ? 'It is' : 'They are'} in the ` +
-            `file, but most BPMN tools will not draw ${undrawn === 1 ? 'it' : 'them'}: ` +
-            `only a pool has a shape to hold ${undrawn === 1 ? 'it' : 'them'}. ` +
-            `Draw ${undrawn === 1 ? 'it' : 'them'} inside a pool to make ` +
-            `${undrawn === 1 ? 'it' : 'them'} visible.`);
+        const [key, fallback] = UNDRAWN_ARTEFACTS_WARNING;
+        warnings.push({ key, fallback, params: { count: undrawn } });
     }
     if (droppedMessageFlows > 0) {
-        warnings.push(`${droppedMessageFlows} message ${droppedMessageFlows === 1 ? 'flow was' : 'flows were'} ` +
-            `left out: a message flow runs between participants, and this board ` +
-            `has no pool. Draw the pools it runs between, or say "is followed by" ` +
-            `instead.`);
+        const [key, fallback] = DROPPED_MESSAGE_FLOWS_WARNING;
+        warnings.push({ key, fallback, params: { count: droppedMessageFlows } });
     }
     // An id a file gave us that we could not give back (ADR 0012 D3). It happens
     // when two elements carry the same recorded id — a merged document, an
@@ -1497,11 +1560,8 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
     // file is correct either way; what the author loses is the continuity of one
     // name between the document they imported and the one they are exporting.
     if (minter.substituted > 0) {
-        warnings.push(`${minter.substituted} ${minter.substituted === 1 ? 'element' : 'elements'} ` +
-            `imported from a BPMN file could not keep ` +
-            `${minter.substituted === 1 ? 'its' : 'their'} original id: ` +
-            `${minter.substituted === 1 ? 'it was' : 'they were'} already taken in ` +
-            `this file. A new id was written instead; nothing else changed.`);
+        const [key, fallback] = SUBSTITUTED_IDS_WARNING;
+        warnings.push({ key, fallback, params: { count: minter.substituted } });
     }
     // A carried diagram element keeps the source file's own coordinates, and the
     // rest of the drawing has just been translated to the plane origin (§12.3).
@@ -1510,44 +1570,28 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
     // once anything has been dragged. Nothing is lost; something is displaced,
     // and the person who clicked Export is the one entitled to hear about it.
     if (carriedPlane.length > 0 && (dx !== 0 || dy !== 0)) {
-        const count = carriedPlane.length;
-        warnings.push(`${count} ${count === 1 ? 'shape' : 'shapes'} imported from a BPMN file ` +
-            `${count === 1 ? 'is' : 'are'} kept exactly as the file drew ` +
-            `${count === 1 ? 'it' : 'them'}, and the rest of this drawing has ` +
-            `moved since. ${count === 1 ? 'It' : 'They'} will open beside the ` +
-            `process rather than inside it. Nothing was lost: ` +
-            `${count === 1 ? 'it is' : 'they are'} in the file, at the position ` +
-            `the original gave ${count === 1 ? 'it' : 'them'}.`);
+        const [key, fallback] = DISPLACED_SHAPES_WARNING;
+        warnings.push({ key, fallback, params: { count: carriedPlane.length } });
     }
     if (contradictingDeclarations.length > 0) {
-        const one = contradictingDeclarations.length === 1;
-        warnings.push(`This board came from a BPMN file that used ` +
-            `${contradictingDeclarations.join(' and ')} for something other than ` +
-            `what BPMN means by ${one ? 'it' : 'them'}. ` +
-            `Labre writes its own, so the file's ` +
-            `${one ? 'declaration was' : 'declarations were'} ` +
-            `left out rather than allowed to redefine the diagram's own namespaces. ` +
-            `${one ? 'It is' : 'They are'} still in the document. ` +
-            // The half a reader would otherwise have to work out: the DECLARATION
-            // is what was dropped, and the matter written under it was not — so it
-            // is now read under Labre's binding of the same prefix, which means
-            // something else. That is the larger of the two changes and it was the
-            // silent one.
-            `Anything the file wrote under ` +
-            `${one ? 'that prefix' : 'those prefixes'} is still in the export and ` +
-            `will now be read under Labre's meaning of ` +
-            `${one ? 'it' : 'them'}, which is not the meaning the original had.`);
+        const [key, fallback] = CONTRADICTING_DECLARATIONS_WARNING;
+        warnings.push({
+            key,
+            fallback,
+            params: { names: contradictingDeclarations.join(' and ') },
+        });
     }
     // Two pools, two source files, one prefix bound two ways. Last one wins —
     // there is one attribute of each name on `definitions` and something has to
     // be written — but a rebinding nobody was told about is how a fragment comes
     // to mean something else with no trace of when.
     if (disagreeingDeclarations.length > 0) {
-        warnings.push(`Two pools on this board disagree about ` +
-            `${disagreeingDeclarations.join(' and ')}: they came from BPMN files ` +
-            `that gave the same name two different values. The last was written ` +
-            `and the other left out, so matter carried from the first file is now ` +
-            `read under the second's meaning. Both are still in the document.`);
+        const [key, fallback] = DISAGREEING_DECLARATIONS_WARNING;
+        warnings.push({
+            key,
+            fallback,
+            params: { names: disagreeingDeclarations.join(' and ') },
+        });
     }
     // A carried element claiming an id another has already written back. The
     // duplicate-by-paste case is silent on purpose — one thing carried twice is
@@ -1555,32 +1599,27 @@ export function exportBpmnXmlWithWarnings(board, options = {}) {
     // fragments claiming one id, which is a file that cannot hold both.
     const conflicting = [...new Set(carried.conflictingIds)];
     if (conflicting.length > 0) {
-        const one = conflicting.length === 1;
-        warnings.push(`${conflicting.length} ${one ? 'element' : 'elements'} imported from a ` +
-            `BPMN file could not be written back: ` +
-            `${conflicting.map(id => `"${id}"`).join(', ')} ` +
-            `${one ? 'names an id' : 'name ids'} another imported element had ` +
-            `already claimed, and a BPMN id must be unique across a document. The ` +
-            `first was kept. ${one ? 'The other is' : 'The others are'} still in ` +
-            `the document; ${one ? 'it is' : 'they are'} not in this file.`);
+        const [key, fallback] = CONFLICTING_IDS_WARNING;
+        warnings.push({
+            key,
+            fallback,
+            params: {
+                count: conflicting.length,
+                names: conflicting.map(id => `"${id}"`).join(', '),
+            },
+        });
     }
     // An attribute NAME that is not a name. It cannot be written without
     // unbalancing the document — the serializer interpolates a name and escapes
     // only a value — so it is dropped rather than allowed to corrupt the file.
     const refusedNames = [...new Set(carried.refusedNames)];
     if (refusedNames.length > 0) {
-        const one = refusedNames.length === 1;
-        warnings.push(`${refusedNames.length} carried ${one ? 'attribute' : 'attributes'} ` +
-            `could not be written back, because ` +
-            `${one ? 'its name is not' : 'their names are not'} a valid XML name. ` +
-            `${one ? 'It is' : 'They are'} still in the document. This is a sign ` +
-            `the payload was edited by something other than a BPMN import.`);
+        const [key, fallback] = REFUSED_ATTRIBUTE_NAMES_WARNING;
+        warnings.push({ key, fallback, params: { count: refusedNames.length } });
     }
     if (unwritableEdges > 0) {
-        warnings.push(`${unwritableEdges} ${unwritableEdges === 1 ? 'arrow was' : 'arrows were'} ` +
-            `left out: BPMN requires both ends of a flow to be named, and ` +
-            `${unwritableEdges === 1 ? 'this one has' : 'these have'} an end that ` +
-            `is loose or attached to something that is not a BPMN artefact.`);
+        const [key, fallback] = UNWRITABLE_EDGES_WARNING;
+        warnings.push({ key, fallback, params: { count: unwritableEdges } });
     }
     return {
         text: `<?xml version="1.0" encoding="UTF-8"?>\n${serializeElement(definitions, '')}\n`,

package/dist/import.d.ts

@@ -1,22 +1,34 @@
-import type { InterchangeImportContext, InterchangeImportResult } from '@formicoidea/labre-core/blocks/surface';
+import { type InterchangeImportContext, type InterchangeImportResult } from '@formicoidea/labre-core/blocks/surface';
 import type { BpmnNodeKind } from '@formicoidea/labre-core/model';
 import { BPMN_SCOPE } from './export.js';
 /**
- * The remarks whose wording is FIXED, as `[key, English]` pairs.
+ * The remarks whose wording is FIXED, as `[key, English]` pairs — one entry
+ * per SHAPE of sentence, never one per exact string: a remark that names
+ * something out of the file (`<boundaryEvent>`, an id, a count of lanes)
+ * carries `{{name}}` / `{{count}}` holes in the fallback here, filled at the
+ * call site by `messageParams` (`InterchangeNote.messageParams`) — never by
+ * minting a new key for every value the file happens to carry.
  *
  * A reader is a pure function of text (`docs/adr/0012`, P3) and has no `std`,
- * so it cannot ask the host's catalogue for anything: it declares the key on
- * the note and `reportInterchangeImport` resolves it when it draws the report
- * (`InterchangeNote.messageKey`). The English string stays here and stays the
- * fallback, so the console table and a playground with no catalogue read
- * exactly what they read before.
+ * so it cannot ask the host's catalogue for anything: it declares the key
+ * (and, where the sentence has a hole, the params) on the note, and
+ * `reportInterchangeImport` resolves both when it draws the report
+ * (`InterchangeNote.messageKey` / `.messageParams`). The English string stays
+ * here and stays the fallback, so the console table and a playground with no
+ * catalogue read exactly what they read before: `translateKey` fills a
+ * `{{…}}` hole from `messageParams` even with no `TranslationProvider`
+ * registered (`fillPlaceholders`), so the ENGLISH sentence a call site builds
+ * is unchanged by giving it a key.
  *
- * These three and no others, and the line is not arbitrary: every remaining
- * remark NAMES something out of the file — `<boundaryEvent>`, an id, a count of
- * lanes — and the seam has neither interpolation nor pluralisation. A key for
- * one of those would be a sentence with holes in it that a translator cannot
- * see the shape of, which is the same refusal the interchange count labels
- * already make (`interchange-import.ts`).
+ * Plural wording is the host's: where a count can be 0, 1 or many, the
+ * fallback stays grammatically neutral (`'{{count}} lane(s)…'`) rather than
+ * picking English's own singular/plural — the same rule
+ * `interchange-import.ts`'s own count labels follow.
+ *
+ * `BPMN_QUARANTINE_REASON` (declared further down, with its own key pairing)
+ * is the one exception: its plain string is ALSO written verbatim into
+ * `ForeignInterchange.quarantined[].reason` (data, never translated), so it
+ * cannot become a `[key, english]` pair without breaking that contract.
  *
  * They are contributed to the manifest by `./translations.ts`, with the
  * framework, because they ship in the BPMN bundle rather than in core.
@@ -25,6 +37,32 @@ export declare const BPMN_IMPORT_REMARKS: {
     readonly inventedPool: readonly ["com.labre.bpmn.import.remark.invented-pool", "This file names no participant, so its process was drawn in a pool of Labre's own. The pool is not the file's: exporting writes the process back without one."];
     readonly laneGap: readonly ["com.labre.bpmn.import.remark.lane-gap", "The lanes of this pool are drawn with a gap or an overlap between them. Labre lays its bands end to end, so their heights were kept in proportion and the space between them was closed."];
     readonly mustUnderstand: readonly ["com.labre.bpmn.import.remark.must-understand", "The file declares an extension that it says MUST be understood to read the model correctly. Labre does not understand it: the import went ahead, and this reading of the process may be wrong."];
+    readonly duplicateId: readonly ["com.labre.bpmn.import.remark.duplicate-id", "Two elements in this file share the id \"{{id}}\", which BPMN requires to be unique across a document. Both were imported; the second will be written back under an id Labre mints."];
+    readonly carriedChild: readonly ["com.labre.bpmn.import.remark.carried-child", "<{{tag}}> has no Labre artefact, so it is kept verbatim on the nearest element that has one. It is not drawn, and no validation rule sees it."];
+    readonly inventedPoolLayout: readonly ["com.labre.bpmn.import.remark.invented-pool-layout", "The participant \"{{name}}\" arrived with no diagram, so Labre placed its pool beside the drawing."];
+    readonly inventedLaneLayout: readonly ["com.labre.bpmn.import.remark.invented-lane-layout", "{{count}} lane(s) arrived with no diagram, so Labre split the pool into equal bands. The proportions are Labre's and not the file's."];
+    readonly undrawnTrigger: readonly ["com.labre.bpmn.import.remark.undrawn-trigger", "<{{tag}}> names its trigger by reference to \"{{ref}}\", which Labre does not draw. The event was kept whole rather than drawn as a plain one."];
+    readonly inventedNodeLayout: readonly ["com.labre.bpmn.import.remark.invented-node-layout", "<{{tag}}> arrived with no diagram, so Labre placed it beside the drawing. Its position is Labre's and not the file's."];
+    readonly singleEndedFlow: readonly ["com.labre.bpmn.import.remark.single-ended-flow", "<{{tag}}> names only one of its two ends, so there is no arrow to draw between them. It was left out."];
+    readonly danglingFlowEnd: readonly ["com.labre.bpmn.import.remark.dangling-flow-end", "<{{tag}}> runs to {{ends}}, not drawn on this canvas. The flow is kept whole beside them rather than drawn with a loose end."];
+    readonly undeclaredShape: readonly ["com.labre.bpmn.import.remark.undeclared-shape", "The diagram draws \"{{id}}\", which the file does not declare. The shape is kept, and nothing is drawn for it."];
+    readonly noProcessResidue: readonly ["com.labre.bpmn.import.remark.no-process-residue", "This file declares {{count}} root element(s) and no process to draw, so there was no artefact for them to be kept on. Nothing was imported."];
+    readonly laneDrift: readonly ["com.labre.bpmn.import.remark.lane-drift", "The file lists this artefact in the lane \"{{listedLane}}\" and draws it in \"{{drawnLane}}\". Labre reads the drawing: a lane holds what is drawn inside it."];
+    readonly inventedRouting: readonly ["com.labre.bpmn.import.remark.invented-routing", "{{count}} flow(s) carry an explicit routing in the file. Labre routes a flow between its two ends and re-routes it whenever they move, so their bend points are not kept."];
+};
+/**
+ * The reader's own refusals, as `[key, English]` pairs — thrown via
+ * {@link InterchangeImportError}, never returned, because none of these say
+ * "this is a file I can partly read" (see `parseDefinitions` and the
+ * choreography refusal, below). Same shape and the same reason as
+ * {@link BPMN_IMPORT_REMARKS}: one entry per shape of refusal, `{{name}}`
+ * holes filled by `InterchangeImportError.messageParams`.
+ */
+export declare const BPMN_IMPORT_ERRORS: {
+    readonly malformedXml: readonly ["com.labre.bpmn.import.error.malformed-xml", "This file is not well-formed XML, so no BPMN can be read out of it: {{detail}}"];
+    readonly notDefinitions: readonly ["com.labre.bpmn.import.error.not-definitions", "A BPMN file opens on <definitions>; this one opens on <{{tag}}>."];
+    readonly wrongNamespace: readonly ["com.labre.bpmn.import.error.wrong-namespace", "This <definitions> is in \"{{namespace}}\", not in BPMN 2.0's (\"{{bpmnNamespace}}\"). A DMN decision model and a BPMN process open on the same element name and are not the same file."];
+    readonly declinedRootKind: readonly ["com.labre.bpmn.import.error.declined-root-kind", "This file is a BPMN {{kind}}, which Labre does not draw. Only a process or a collaboration can be imported."];
 };
 /**
  * `startEvent` + `messageEventDefinition` → `startEventMessage`, and the
@@ -60,6 +98,20 @@ export declare const BPMN_QUARANTINE_REASON: {
     readonly nestedLanes: string;
     readonly imported: string;
 };
+/**
+ * {@link BPMN_QUARANTINE_REASON}'s own i18n keys, one per reason.
+ *
+ * A SEPARATE table rather than folding the key into each reason string
+ * (`BPMN_IMPORT_REMARKS`'s `[key, english]` shape): `BPMN_QUARANTINE_REASON`'s
+ * plain strings are ALSO written verbatim into
+ * `ForeignInterchange.quarantined[].reason` — a DATA field the reader hands
+ * the writer, never re-emitted, never shown, and pinned in
+ * `import.unit.spec.ts` as the literal English text — so it cannot become a
+ * tuple without breaking that contract. Only the REPORT note (`messageKey`
+ * below) is resolved through the host's catalogue; the carried `reason` data
+ * stays English, exactly as it always has.
+ */
+export declare const BPMN_QUARANTINE_REASON_KEY: Record<keyof typeof BPMN_QUARANTINE_REASON, string>;
 /**
  * Read a BPMN 2.0 interchange document as element props plus a report.
  *