@formicoidea/labre-framework-uml 0.42.0

package/dist/model.js

@@ -0,0 +1,1316 @@
+import { UML_DIAGRAM_KIND_TAG, UML_FRAGMENT_BAND, UML_FRAME_BAND_HEIGHT, UML_LIFELINE_HEAD, } from '@formicoidea/labre-core/model';
+import { umlComponentSiblings, umlGroupOf, umlTierText, } from './component.js';
+import { parseActivityEdge, parseCompartment, parseEndLabel, parseLifelineIdent, parseOperation, parseProperty, parseStateBehavior, parseTransition, } from './grammar.js';
+import { stereotypesOf } from './keywords.js';
+import { UML_ROLE } from './roles.js';
+/**
+ * The relationships whose end labels §11.5.4 gives a MEANING to.
+ *
+ * An Association and its two aggregation flavours, plus the CommunicationPath
+ * §19.4.3 defines as "an Association between two DeploymentTargets" — which is
+ * why it is in the set: it is an Association, so its ends are Properties and
+ * take a multiplicity like any other.
+ */
+export const ADORNED_RELATION_KINDS = new Set([
+    'association',
+    'aggregation',
+    'composition',
+    'communication-path',
+]);
+/* ── Roles ────────────────────────────────────────────────────────────── */
+/**
+ * The connector role that states each relationship — C1's vocabulary, read
+ * rather than re-spelled.
+ *
+ * `Record<UmlRelationKind, string>` and therefore compile-total in both
+ * directions: a relation kind with no role fails here, and a role renamed in
+ * `roles.ts` fails here too rather than silently exporting nothing.
+ */
+const RELATION_ROLE = {
+    association: UML_ROLE.association,
+    aggregation: UML_ROLE.aggregation,
+    composition: UML_ROLE.composition,
+    generalization: UML_ROLE.generalization,
+    realization: UML_ROLE.realization,
+    dependency: UML_ROLE.dependency,
+    anchor: UML_ROLE.anchor,
+    include: UML_ROLE.include,
+    extend: UML_ROLE.extend,
+    deploy: UML_ROLE.deploy,
+    manifest: UML_ROLE.manifest,
+    'communication-path': UML_ROLE['communication-path'],
+    'control-flow': UML_ROLE['control-flow'],
+    'object-flow': UML_ROLE['object-flow'],
+    transition: UML_ROLE.transition,
+    'message-sync': UML_ROLE['message-sync'],
+    'message-async': UML_ROLE['message-async'],
+    'message-reply': UML_ROLE['message-reply'],
+    'message-create': UML_ROLE['message-create'],
+    'message-delete': UML_ROLE['message-delete'],
+};
+/** The five message kinds, as a set — what tells a message from a relation. */
+const MESSAGE_KINDS = new Set([
+    'message-sync',
+    'message-async',
+    'message-reply',
+    'message-create',
+    'message-delete',
+]);
+const RELATION_OF_ROLE = new Map(Object.entries(RELATION_ROLE).map(([kind, role]) => [
+    role,
+    kind,
+]));
+/* ── Geometry ─────────────────────────────────────────────────────────── */
+/**
+ * An element's box, from whichever of the three spellings it carries.
+ *
+ * `deserializedXYWH` first because that is what a live element answers with;
+ * `elementBound` because that is what the shared canvas fixtures build; the
+ * serialized `xywh` last, for a record that carries only what the store holds.
+ */
+export function umlBoundsOf(element) {
+    const xywh = element.deserializedXYWH;
+    if (xywh && xywh.length >= 4) {
+        return { x: xywh[0], y: xywh[1], w: xywh[2], h: xywh[3] };
+    }
+    const bound = element.elementBound;
+    if (bound && typeof bound.x === 'number') {
+        return { x: bound.x, y: bound.y, w: bound.w, h: bound.h };
+    }
+    if (typeof element.xywh === 'string') {
+        const parts = element.xywh
+            .replace(/^\[/, '')
+            .replace(/\]$/, '')
+            .split(',')
+            .map(Number);
+        if (parts.length >= 4 && parts.every(Number.isFinite)) {
+            return { x: parts[0], y: parts[1], w: parts[2], h: parts[3] };
+        }
+    }
+    return undefined;
+}
+/** Inclusive containment of a box's CENTRE in another box. */
+export function umlCentreInside(inner, outer) {
+    const cx = inner.x + inner.w / 2;
+    const cy = inner.y + inner.h / 2;
+    return (cx >= outer.x &&
+        cx <= outer.x + outer.w &&
+        cy >= outer.y &&
+        cy <= outer.y + outer.h);
+}
+/**
+ * How near a glyph has to be drawn to count as attached to a box, in model
+ * units.
+ *
+ * The one number this file invents, and the reason it is small: §10.4.4 and
+ * §11.3.4 both describe a symbol TOUCHING a rectangle — a lollipop "attached by
+ * a solid line" to the classifier that realizes it, a port "overlapping the
+ * boundary" of the box it is on. Touching is a gap of zero, and a hand drawing
+ * on a canvas misses by a few units, so the tolerance is a couple of grid steps
+ * and not a neighbourhood: an interface glyph parked halfway across the sheet is
+ * not this component's, and a reading that guessed would put an interface in the
+ * file that nobody drew.
+ *
+ * Read by {@link umlHostOf} and by {@link umlBoxGap}'s callers alike, so the
+ * port's owner and the interface's component are decided by the same distance.
+ */
+export const UML_ATTACH_TOLERANCE = 24;
+/**
+ * The GAP between two boxes — zero when they touch or overlap, otherwise the
+ * shortest distance from edge to edge.
+ *
+ * Edges, never centres: a lollipop is thirty units across and a component two
+ * hundred, so "nearest centre" would hand a glyph to whichever box happens to be
+ * squattest rather than to the one it is drawn against. The same argument
+ * `gapSquared` makes in the validation engine, one package over.
+ */
+export function umlBoxGap(a, b) {
+    const dx = Math.max(0, Math.max(a.x - (b.x + b.w), b.x - (a.x + a.w)));
+    const dy = Math.max(0, Math.max(a.y - (b.y + b.h), b.y - (a.y + a.h)));
+    return Math.hypot(dx, dy);
+}
+/**
+ * The DRAWING area of a diagram frame — the frame minus its heading band.
+ *
+ * The same carve-out `c4/export.ts` makes with `backgroundPlot`, arrived at from
+ * the MODEL's own constant so this module owes the framework declaration
+ * nothing: the top margin is where the frame writes its own heading
+ * (`UmlDiagramElementModel`), and an element laid over the heading is on the
+ * sheet's chrome rather than on its drawing area.
+ */
+export function umlSheetOf(frame) {
+    const band = Math.min(UML_FRAME_BAND_HEIGHT, frame.h);
+    return { x: frame.x, y: frame.y + band, w: frame.w, h: frame.h - band };
+}
+/**
+ * Which box a glyph is drawn AGAINST — the one reading that gives a port its
+ * owner and a lollipop its component.
+ *
+ * The nearest host within {@link UML_ATTACH_TOLERANCE}, and `undefined` when
+ * nothing is that near: a port drawn in the middle of the sheet belongs to
+ * nothing, and inventing an owner for it would put a `uml:Port` on a component
+ * the author never drew it on.
+ *
+ * ## The tie-breaks, and why there are two of them
+ *
+ * A component nested inside another (§11.6.4's white-box view) puts a port on
+ * the boundary of BOTH, at a gap of zero from each. The smaller box wins,
+ * because the most-nested container is the one the author was aiming at — the
+ * same reading `containerOf` makes in the two writers. And an exact tie on both
+ * gap and area is broken by the smaller id, never by the order the surface
+ * happened to be walked in: this decides what a FILE says, and a Y.Map rebuilt
+ * on every load does not promise an order.
+ */
+export function umlHostOf(glyph, hosts, tolerance = UML_ATTACH_TOLERANCE) {
+    if (!glyph)
+        return undefined;
+    let best;
+    let bestGap = Number.POSITIVE_INFINITY;
+    let bestArea = Number.POSITIVE_INFINITY;
+    for (const host of hosts) {
+        if (!host.bounds)
+            continue;
+        const gap = umlBoxGap(glyph, host.bounds);
+        if (gap > tolerance)
+            continue;
+        const area = Math.max(0, host.bounds.w) * Math.max(0, host.bounds.h);
+        const better = gap < bestGap ||
+            (gap === bestGap &&
+                (area < bestArea ||
+                    (area === bestArea && best !== undefined && host.id < best.id)));
+        if (better) {
+            best = host;
+            bestGap = gap;
+            bestArea = area;
+        }
+    }
+    return best;
+}
+/* ── The sequence sheet's own geometry (§17.2.4) ──────────────────────── */
+/**
+ * The x of a lifeline's SPINE — the dashed line everything on a sequence sheet
+ * is measured against.
+ *
+ * The centre of the element's own box, which is the column and not the head:
+ * `UmlNodeElementModel` makes a lifeline a narrow tall column so that the
+ * connector layer's native anchors land on the spine, and paints the 160-wide
+ * head over the top of it. So the spine is the column's own centre line, and
+ * this function exists so that the four readers below cannot each decide that
+ * differently.
+ */
+export function umlSpineX(lifeline) {
+    return lifeline.x + lifeline.w / 2;
+}
+/**
+ * How far off a spine a bar or a cross may be drawn and still be ON it.
+ *
+ * Half the HEAD's width, and it is the notation's own number rather than a
+ * guess: §17.2.4 draws an ExecutionSpecification as a bar centred on the spine
+ * and a destruction as a cross centred on it, so the honest tolerance is "nearer
+ * to this spine than to any other", and lifelines laid out at the 200-unit
+ * spacing of an invented sequence layout are 200 apart. 80 is inside that by a
+ * comfortable margin, so a bar dropped a little off centre finds its own
+ * lifeline and a bar dropped between two finds neither.
+ */
+export const UML_SPINE_TOLERANCE = UML_LIFELINE_HEAD.w / 2;
+/**
+ * Which lifeline a bar or a cross is drawn ON — {@link umlHostOf}'s twin for
+ * §17.2.4's two glyphs.
+ *
+ * A different reading from `umlHostOf` and deliberately so: a port is attached
+ * to a box by TOUCHING it, and a bar is attached to a spine by SITTING ON it —
+ * one is an edge-to-edge gap, the other a distance from one vertical line. The
+ * nearest spine within {@link UML_SPINE_TOLERANCE} wins; an exact tie is broken
+ * by the smaller id, never by the order the surface happened to be walked in,
+ * for the reason `umlHostOf` gives: this decides what a FILE says.
+ *
+ * `undefined` when nothing is that near — a bar drawn between two spines belongs
+ * to neither, and inventing an owner for it would put an execution on a
+ * participant the author never drew it on.
+ */
+export function umlLifelineAt(glyph, lifelines) {
+    if (!glyph)
+        return undefined;
+    const cx = glyph.x + glyph.w / 2;
+    let best;
+    let bestGap = Number.POSITIVE_INFINITY;
+    for (const lifeline of lifelines) {
+        if (!lifeline.bounds)
+            continue;
+        const gap = Math.abs(cx - umlSpineX(lifeline.bounds));
+        if (gap > UML_SPINE_TOLERANCE)
+            continue;
+        if (gap < bestGap || (gap === bestGap && best && lifeline.id < best.id)) {
+            best = lifeline;
+            bestGap = gap;
+        }
+    }
+    return best;
+}
+/**
+ * The operand bands of a combined fragment, as boxes — §17.6.4's horizontal
+ * slices, separated by dashed lines.
+ *
+ * The operator BAND is carved off the top first (`UML_FRAGMENT_BAND`), exactly
+ * as `umlSheetOf` carves the frame's heading off: the pentagon is the
+ * fragment's own chrome, and a guard written over it is on the furniture rather
+ * than in an operand.
+ *
+ * `size` is a relative WEIGHT (`UmlFragmentOperand`), so the bands are the body
+ * divided in proportion — a fragment dragged taller keeps its operands' shares.
+ * A fragment that declares no operands is ONE operand, which is what every
+ * `opt`, every `loop` and every `ref` is, and its guard is the fragment's own
+ * `name`.
+ */
+/**
+ * A guard as the IR spells it — §17.6.4's condition with ONE surrounding pair
+ * of brackets taken off.
+ *
+ * The canvas text is exactly what the author types, and §17.6.4.4 prints the
+ * condition **in brackets**: `[x > 0]`, `[else]`. So the brackets are stored,
+ * the renderer paints them verbatim, and the delimiter is stripped HERE, once,
+ * for both writers — PlantUML writes its own `[…]` back round the condition and
+ * XMI writes a bare `LiteralString`, and neither should have to parse the
+ * model it is given.
+ *
+ * Tolerant in both directions, because a guard is free text an author types:
+ * `x > 0` typed without brackets is the same condition and exports identically,
+ * and `[[x > 0]]` gives up exactly one pair. Only a pair that actually
+ * SURROUNDS the condition is taken — `[a] or [b]` opens and closes twice, and
+ * dropping its outer characters would turn a sentence inside out.
+ */
+export function umlGuardText(written) {
+    const text = (written ?? '').trim();
+    if (text.length < 2 || !text.startsWith('[') || !text.endsWith(']')) {
+        return text;
+    }
+    let depth = 0;
+    for (const [index, character] of [...text].entries()) {
+        if (character === '[')
+            depth += 1;
+        else if (character === ']') {
+            depth -= 1;
+            if (depth === 0 && index < text.length - 1)
+                return text;
+        }
+    }
+    return depth === 0 ? text.slice(1, -1).trim() : text;
+}
+export function umlOperandBands(box, operands, name) {
+    const band = Math.min(UML_FRAGMENT_BAND, box.h);
+    const top = box.y + band;
+    const body = Math.max(0, box.h - band);
+    const guardOf = (index, written) => {
+        // …and the brackets come OFF here (see {@link umlGuardText}): the canvas
+        // holds `[x > 0]` because that is what §17.6.4 draws and what the author
+        // typed, and the IR holds the condition.
+        const guard = umlGuardText(written ?? (index === 0 ? name : ''));
+        return guard ? { guard } : {};
+    };
+    if (!operands || operands.length === 0) {
+        return [{ ...guardOf(0, undefined), y0: top, y1: top + body }];
+    }
+    const weights = operands.map(operand => Number.isFinite(operand.size) && operand.size > 0 ? operand.size : 1);
+    const total = weights.reduce((sum, weight) => sum + weight, 0);
+    const bands = [];
+    let y = top;
+    for (const [index, operand] of operands.entries()) {
+        // The LAST band is closed on the box rather than on the running sum, so
+        // rounding cannot leave a sliver of the fragment in no operand at all.
+        const next = index === operands.length - 1
+            ? top + body
+            : y + (body * weights[index]) / total;
+        bands.push({ ...guardOf(index, operand.name), y0: y, y1: next });
+        y = next;
+    }
+    return bands;
+}
+/** The classifier kinds — the four that carry compartments. */
+const CLASSIFIER_KINDS = new Set([
+    'class',
+    'interface',
+    'enumeration',
+    'object',
+]);
+/** The glyphs only an ACTIVITY draws — §15.3.4, §15.4.4, §16.3.4, §16.10.4. */
+const ACTIVITY_ONLY_KINDS = new Set([
+    'action',
+    'activity-final',
+    'flow-final',
+    'decision',
+    'object-node',
+    'send-signal',
+    'accept-event',
+    'time-event',
+]);
+/** The pseudostates only a STATE MACHINE draws — §14.2.4.6. */
+const PSEUDOSTATE_ONLY_KINDS = new Set([
+    'choice',
+    'junction',
+    'shallow-history',
+    'deep-history',
+    'entry-point',
+    'exit-point',
+    'terminate',
+]);
+/**
+ * The two glyphs BOTH behaviour sheets draw, and the one ambiguity this file
+ * has to resolve rather than report.
+ *
+ * §15.3.4 and §14.2.4 draw the same filled disc and the same solid bar and mean
+ * the same thing by each — a beginning, a split or a join — which is why
+ * `roles.ts` gives each ONE role instead of two. A role is a statement about
+ * meaning and the meaning is genuinely the same; an EXPORT, though, has to put
+ * the disc in an `uml:Activity` or in a `uml:StateMachine`, and those are two
+ * different metaclasses in two different packages.
+ *
+ * So the sheet's own heading decides: on an `stm` frame the disc is a
+ * `Pseudostate kind="initial"` and the bar a `Pseudostate kind="fork"`, and
+ * everywhere else they are an `InitialNode` and a `ForkNode`. Annex A makes that
+ * heading a required part of the frame (`kinds.ts`), so the statement is always
+ * there to read — and it is the author's own, which is the only thing that could
+ * honestly settle this.
+ */
+const UML_SHARED_BEHAVIOUR_KINDS = new Set(['initial', 'fork']);
+/**
+ * One diagram, read off a flat element list.
+ *
+ * ## What belongs to it
+ *
+ * Geometry, exactly as every other framework in this library attributes: an
+ * element is on this sheet when its CENTRE is inside the frame's drawing area.
+ * Selecting a frame therefore selects what is drawn on it, and a second frame
+ * beside it is a second diagram — the reading `c4/export.ts` argues for at
+ * length, and the reason UML ships four diagram kinds on one canvas (ADR 0017).
+ *
+ * ## How an end finds its artefact
+ *
+ * A UML node is drawn as a GROUP — a shape plus its written tiers — and every
+ * part of that group is connectable. An arrow dragged onto a class records the
+ * id of the group, of the name tier or of the attribute tier about as often as
+ * the shape's, and all four look identical to the person drawing it. So each
+ * part answers for its shape, and only where the group holds exactly ONE UML
+ * node: a lasso somebody drew round two classes points at neither in
+ * particular, and guessing there would put a relationship in the file that
+ * nobody drew.
+ *
+ * ## Two things geometry decides, and nothing else does
+ *
+ * Phase 2 added the only readings in this file that measure one element against
+ * ANOTHER element: which component a PORT sits on (§11.3.4) and which component
+ * a lollipop or a socket is drawn against (§10.4.4, §11.6.4). Both are the
+ * notation's own statement — the specification describes a small symbol placed
+ * on or touching a rectangle, and a whiteboard holds no second link to read — so
+ * the reading is {@link umlHostOf} and the tolerance is
+ * {@link UML_ATTACH_TOLERANCE}. A glyph that touches nothing is kept on the
+ * drawing and written into no file, which is the same call the rest of this
+ * module makes about anything it cannot attribute.
+ *
+ * ## What is warned about
+ *
+ * Two things, and both are a line the author DREW that the file cannot carry: a
+ * typed relationship with an end this diagram cannot resolve, and a connector
+ * between two UML nodes carrying no role at all. The second is not an error —
+ * `docs/adr/0010` is explicit that the role IS the statement, so a bare
+ * connector relates nothing — but a user who drew a line between two classes
+ * and gets a file without it is owed the sentence.
+ *
+ * Neither is said about a connector that is not this sheet's. A line belongs to
+ * this diagram when at least one of its ends resolves to an artefact of it, or —
+ * for a line attached to nothing — when its own centre is inside the sheet.
+ * Anything else is another frame's drawing, and warning about it would mean
+ * every export of a two-frame board complaining about lines that are perfectly
+ * drawn next door.
+ */
+export function umlModelFrom(diagram, elements, options = {}) {
+    const siblingsOf = options.siblingsOf ?? umlComponentSiblings;
+    const warnings = [];
+    const frame = umlBoundsOf(diagram);
+    const sheet = frame ? umlSheetOf(frame) : undefined;
+    const onSheet = (element) => {
+        if (!sheet)
+            return true;
+        const bounds = umlBoundsOf(element);
+        return bounds ? umlCentreInside(bounds, sheet) : false;
+    };
+    const groups = [];
+    const nodes = [];
+    const subjects = [];
+    const connectors = [];
+    /** §15.6.4's swimlanes and §14.2.4's composite states — the two new frames. */
+    const partitionElements = [];
+    const regionElements = [];
+    /** §17.6.4's combined fragments — phase 3's frame. */
+    const fragmentElements = [];
+    /** Every element's own box, by its own id — what a message's height is read
+     * off (a connector's end names the ELEMENT it touches, which may be a tier or
+     * a group rather than the node the end resolves to). */
+    const boxOfElement = new Map();
+    for (const element of elements) {
+        if (Array.isArray(element.childIds)) {
+            groups.push({ id: element.id, childIds: element.childIds });
+        }
+        const box = umlBoundsOf(element);
+        if (box)
+            boxOfElement.set(element.id, box);
+        if (element.type === 'umlNode')
+            nodes.push(element);
+        else if (element.type === 'umlSubject')
+            subjects.push(element);
+        else if (element.type === 'umlPartition')
+            partitionElements.push(element);
+        else if (element.type === 'umlRegion')
+            regionElements.push(element);
+        else if (element.type === 'umlFragment')
+            fragmentElements.push(element);
+        else if (element.type === 'connector')
+            connectors.push(element);
+    }
+    /** What one node's group says, by tier. */
+    const tiersOf = (node) => {
+        const group = umlGroupOf(node.id, groups);
+        const component = group ? siblingsOf(group, elements) : {};
+        // `label` is the actor's and the use case's tier, `name` the classifier's
+        // and `ident` §17.3.4's lifeline head — one of the three, never two
+        // (`component.ts`). The head is read here rather than anywhere special
+        // because a lifeline's name IS its head: `parseLifelineIdent` takes the
+        // line this returns and splits it into the participant and its classifier.
+        const named = component.name ?? component.label ?? component.ident;
+        return {
+            // The shape's own inner text is a FALLBACK and not a source: a node whose
+            // group was released, or whose tiers were deleted, still states its name
+            // if the shape carries one. The test is EXISTENCE of the tier — a name an
+            // author deliberately cleared has been cleared.
+            name: named ? umlTierText(named.text) : umlTierText(node.text),
+            attributes: umlTierText(component.attributes?.text),
+            operations: umlTierText(component.operations?.text),
+        };
+    };
+    /**
+     * What the frame SAYS it draws — read before the nodes, because two glyphs
+     * are shared between the behaviour sheets and the sheet's own heading is what
+     * tells them apart (see {@link UML_SHARED_BEHAVIOUR_KINDS}).
+     */
+    const diagramKind = diagram.kind ?? 'class';
+    const readsAsStateMachine = diagramKind === 'stm';
+    const classifiers = [];
+    const packages = [];
+    const actors = [];
+    const useCases = [];
+    const notes = [];
+    const subjectBoxes = [];
+    const components = [];
+    const ports = [];
+    const artifacts = [];
+    const deploymentNodes = [];
+    const activityNodes = [];
+    const lifelines = [];
+    const executions = [];
+    const destructions = [];
+    const states = [];
+    const finalStates = [];
+    const pseudostates = [];
+    /** The lollipops and the sockets, held until every box is known. */
+    const providedGlyphs = [];
+    const requiredGlyphs = [];
+    /** Every id that answers for an artefact of this diagram. */
+    const artefactOf = new Map();
+    for (const node of nodes) {
+        if (!onSheet(node))
+            continue;
+        const kind = node.kind;
+        if (!kind)
+            continue;
+        const tiers = tiersOf(node);
+        const stated = stereotypesOf(tiers.name);
+        const bounds = umlBoundsOf(node);
+        const base = {
+            id: node.id,
+            name: stated.name,
+            keywords: stated.keywords,
+            isAbstract: stated.isAbstract,
+            ...(bounds ? { bounds } : {}),
+        };
+        if (CLASSIFIER_KINDS.has(kind)) {
+            const classifierKind = kind;
+            const attributeLines = parseCompartment(tiers.attributes);
+            const operationLines = classifierKind === 'object' ? [] : parseCompartment(tiers.operations);
+            const classifier = {
+                ...base,
+                kind: classifierKind,
+                // An object has no attribute compartment: §11.6.4 gives it SLOTS, and
+                // the same lines are read as one or the other, never as both.
+                attributes: classifierKind === 'object' ? [] : attributeLines.map(parseProperty),
+                operations: operationLines.map(parseOperation),
+                slots: classifierKind === 'object' ? attributeLines.map(slotOf) : [],
+                lines: { attributes: attributeLines, operations: operationLines },
+            };
+            if (classifierKind === 'object') {
+                // `object : Class` (§11.6.4) — the instance name and the Classifier it
+                // instantiates, which is what XMI's `classifier` reference needs.
+                const colon = base.name.indexOf(':');
+                if (colon >= 0) {
+                    classifier.name = base.name.slice(0, colon).trim();
+                    const named = base.name.slice(colon + 1).trim();
+                    if (named)
+                        classifier.instanceOf = named;
+                }
+            }
+            classifiers.push(classifier);
+        }
+        else if (kind === 'package') {
+            packages.push(base);
+        }
+        else if (kind === 'actor') {
+            actors.push(base);
+        }
+        else if (kind === 'use-case') {
+            useCases.push(base);
+        }
+        else if (kind === 'note') {
+            // A note is PROSE: no keyword is lifted out of it and no `{abstract}` is
+            // read off it, because a note that mentions «create» is a note that
+            // mentions it.
+            notes.push({ ...base, name: '', keywords: [], body: tiers.name.trim() });
+        }
+        else if (kind === 'component') {
+            // The ports and the interface names are filled in below, once every box
+            // on the sheet is known: they are read by GEOMETRY, and a glyph drawn
+            // before its component would otherwise find nothing to attach to.
+            components.push({ ...base, ports: [], provided: [], required: [] });
+        }
+        else if (kind === 'port') {
+            ports.push(base);
+        }
+        else if (kind === 'provided-interface' || kind === 'required-interface') {
+            // The lollipop and the socket are the only drawn artefacts that are NOT
+            // elements of the model: §10.4.4 draws each as a notation for a
+            // relationship — an InterfaceRealization, a Usage — between the interface
+            // it names and the classifier it touches, and both writers turn it into
+            // exactly that. So it answers for nothing, which is why this branch does
+            // not reach the `artefactOf` line below: a connector dropped on a lollipop
+            // resolves to no artefact, and the warning says the end is not on the
+            // diagram rather than the file carrying a reference to a circle.
+            (kind === 'provided-interface' ? providedGlyphs : requiredGlyphs).push(base);
+            continue;
+        }
+        else if (kind === 'artifact') {
+            artifacts.push(base);
+        }
+        else if (kind === 'node' ||
+            kind === 'device' ||
+            kind === 'execution-environment') {
+            deploymentNodes.push({ ...base, kind });
+        }
+        else if (ACTIVITY_ONLY_KINDS.has(kind) ||
+            (UML_SHARED_BEHAVIOUR_KINDS.has(kind) && !readsAsStateMachine)) {
+            activityNodes.push({ ...base, kind: kind });
+        }
+        else if (kind === 'lifeline') {
+            // §17.3.4's `<name> : <Type>` — the one compartment a lifeline has, and
+            // the same grammar §11.6.4 gives an instance. `keywords` and `isAbstract`
+            // are `stereotypesOf`'s, read off the head like any other name tier.
+            const ident = parseLifelineIdent(base.name);
+            lifelines.push({
+                ...base,
+                // The `[<selector>]` §17.3.4 allows between the name and the colon is
+                // kept ON the name rather than given a field of its own: it is part of
+                // WHICH participant this is — `customers[3]` is one of a set — and
+                // neither writer has a slot for it (`Lifeline::selector` is a
+                // ValueSpecification, and a whiteboard has drawn no expression). Folded
+                // back here, the head survives out and in; split out, it would be a
+                // third field two writers would drop.
+                name: ident.selector
+                    ? `${ident.name ?? ''}[${ident.selector}]`
+                    : (ident.name ?? ''),
+                ...(ident.type ? { type: ident.type } : {}),
+            });
+        }
+        else if (kind === 'execution') {
+            // The bar's own extent IS the pair of occurrences it runs between
+            // (§17.2.4): the top is the start, the bottom the finish. The lifeline it
+            // sits on is measured below, once every spine on the sheet is known.
+            executions.push({
+                ...base,
+                y0: bounds ? bounds.y : 0,
+                y1: bounds ? bounds.y + bounds.h : 0,
+            });
+        }
+        else if (kind === 'destruction') {
+            destructions.push({
+                ...base,
+                y: bounds ? bounds.y + bounds.h / 2 : 0,
+            });
+        }
+        else if (kind === 'state') {
+            // §14.2.4.4's internal activities compartment. It is the `uml:attributes`
+            // tier — the same tier a class writes its properties in, reused because a
+            // state's compartment is the second one down and the creation site seeds
+            // it with `entry / …`. Every line that is NOT one of the three labels
+            // stays in `lines`, so an internal transition somebody wrote survives.
+            const entry = [];
+            const doActivity = [];
+            const exit = [];
+            const lines = [];
+            for (const line of parseCompartment(tiers.attributes)) {
+                const behavior = parseStateBehavior(line);
+                if (!behavior) {
+                    lines.push(line);
+                    continue;
+                }
+                // A label with nothing after it is a line somebody is halfway through,
+                // and an empty behaviour expression is not a behaviour: it is kept as a
+                // line of the compartment rather than written into a file as a Behavior
+                // with no body.
+                if (!behavior.expression) {
+                    lines.push(line);
+                    continue;
+                }
+                if (behavior.kind === 'entry')
+                    entry.push(behavior.expression);
+                else if (behavior.kind === 'do')
+                    doActivity.push(behavior.expression);
+                else
+                    exit.push(behavior.expression);
+            }
+            states.push({ ...base, entry, doActivity, exit, lines });
+        }
+        else if (kind === 'final-state') {
+            finalStates.push(base);
+        }
+        else if (PSEUDOSTATE_ONLY_KINDS.has(kind) ||
+            (UML_SHARED_BEHAVIOUR_KINDS.has(kind) && readsAsStateMachine)) {
+            pseudostates.push({ ...base, kind: kind });
+        }
+        else {
+            // A kind this build does not draw yet (a later phase widens the union):
+            // it is on the sheet and it answers for itself, but nothing writes it
+            // down.
+            continue;
+        }
+        artefactOf.set(node.id, node.id);
+    }
+    // ── The structural attachments, once every box on the sheet is known ──
+    //
+    // Two geometric readings, and the only two in this file that are about one
+    // element's position relative to ANOTHER element rather than to a frame.
+    // Neither is a fallback for a link the store could have held: §11.3.4 and
+    // §10.4.4 describe a small symbol drawn ON or AGAINST a rectangle, and on a
+    // whiteboard that is the whole of what the author stated.
+    /** A port's host: the component or the cube its square sits on (§11.3.4). */
+    const portHosts = [...components, ...deploymentNodes];
+    const componentById = new Map(components.map(component => [component.id, component]));
+    for (const port of ports) {
+        const host = umlHostOf(port.bounds, portHosts);
+        if (!host)
+            continue;
+        port.ownerId = host.id;
+        // Only a COMPONENT owns a port in the file: `uml:Port` is an
+        // `ownedAttribute` of an EncapsulatedClassifier, and a port drawn on a cube
+        // is a drawing this pack keeps and writes nowhere.
+        componentById.get(host.id)?.ports.push(port);
+    }
+    /**
+     * An interface glyph's component: the box it touches, or the component that
+     * owns the PORT it touches — §11.3.4's "A provided Interface may be shown
+     * using the lollipop notation attached to the Port".
+     */
+    const glyphHosts = [...components, ...ports];
+    const attachInterface = (glyph, provided) => {
+        const name = glyph.name.trim();
+        if (!name)
+            return;
+        const host = umlHostOf(glyph.bounds, glyphHosts);
+        if (!host)
+            return;
+        const owner = componentById.get(host.id) ??
+            componentById.get(ports.find(port => port.id === host.id)?.ownerId ?? '');
+        if (!owner)
+            return;
+        const list = provided ? owner.provided : owner.required;
+        // §11.3.4 lists several interfaces on one lollipop, separated by commas —
+        // and a component that provides the same interface twice says it once.
+        for (const each of name.split(',')) {
+            const trimmed = each.trim();
+            if (trimmed && !list.includes(trimmed))
+                list.push(trimmed);
+        }
+    };
+    for (const glyph of providedGlyphs)
+        attachInterface(glyph, true);
+    for (const glyph of requiredGlyphs)
+        attachInterface(glyph, false);
+    for (const subject of subjects) {
+        if (!onSheet(subject))
+            continue;
+        const bounds = umlBoundsOf(subject);
+        subjectBoxes.push({
+            id: subject.id,
+            name: umlTierText(subject.name),
+            keywords: [],
+            isAbstract: false,
+            ...(bounds ? { bounds } : {}),
+        });
+        artefactOf.set(subject.id, subject.id);
+    }
+    // ── The two behaviour FRAMES, and what they hold ──────────────────────
+    //
+    // Neither is registered in `artefactOf`, and that is the lollipop's precedent
+    // rather than an omission: a swimlane and a composite state are furniture the
+    // author draws responsibility and nesting with, so a flow dropped on one
+    // relates nothing. The warning an author gets for a control flow ending on a
+    // lane is then the right one — an end that is not on the diagram — instead of
+    // a file carrying an arrow into a band.
+    const partitions = [];
+    for (const partition of partitionElements) {
+        if (!onSheet(partition))
+            continue;
+        const bounds = umlBoundsOf(partition);
+        partitions.push({
+            id: partition.id,
+            name: umlTierText(partition.name),
+            keywords: [],
+            isAbstract: false,
+            // The model defaults it, and a fixture that states nothing means the
+            // default rather than an absent band.
+            orientation: partition.orientation === 'horizontal' ? 'horizontal' : 'vertical',
+            nodeIds: [],
+            ...(bounds ? { bounds } : {}),
+        });
+    }
+    const regions = [];
+    for (const region of regionElements) {
+        if (!onSheet(region))
+            continue;
+        const bounds = umlBoundsOf(region);
+        regions.push({
+            id: region.id,
+            name: umlTierText(region.name),
+            keywords: [],
+            isAbstract: false,
+            ...(bounds ? { bounds } : {}),
+        });
+    }
+    // ── The interaction's geometry (§17.2.4, §17.6.4) ─────────────────────
+    //
+    // Two readings, both by MEASURING, and both for the reason §11.3.4's port and
+    // §10.4.4's lollipop are read that way: the notation draws a mark ON a line
+    // and a rectangle AROUND a group of lines, and a whiteboard holds no second
+    // statement about either. A bar off every spine and a fragment over no
+    // lifeline are kept on the drawing and written into no file.
+    for (const execution of executions) {
+        const lifeline = umlLifelineAt(execution.bounds, lifelines);
+        if (lifeline)
+            execution.lifelineId = lifeline.id;
+    }
+    for (const destruction of destructions) {
+        const lifeline = umlLifelineAt(destruction.bounds, lifelines);
+        if (lifeline)
+            destruction.lifelineId = lifeline.id;
+    }
+    const fragments = [];
+    for (const fragment of fragmentElements) {
+        if (!onSheet(fragment))
+            continue;
+        const box = umlBoundsOf(fragment);
+        const written = umlTierText(fragment.name);
+        const operator = fragment.operator ?? 'alt';
+        // A fragment COVERS the lifelines whose spine runs through it (§17.6.4),
+        // ordered left to right — which is the order `ref over a, b` is written in
+        // and the order a reader's eye takes them in.
+        const covered = box
+            ? lifelines
+                .filter(lifeline => {
+                const spine = lifeline.bounds
+                    ? umlSpineX(lifeline.bounds)
+                    : undefined;
+                return (spine !== undefined && spine >= box.x && spine <= box.x + box.w);
+            })
+                .sort((a, b) => {
+                const gap = umlSpineX(a.bounds) - umlSpineX(b.bounds);
+                return gap !== 0 ? gap : a.id < b.id ? -1 : 1;
+            })
+                .map(lifeline => lifeline.id)
+            : [];
+        fragments.push({
+            id: fragment.id,
+            name: written,
+            keywords: [],
+            isAbstract: false,
+            ...(box ? { bounds: box } : {}),
+            // The model defaults it, and a fixture that states nothing means the
+            // default rather than a fragment with no word in its pentagon.
+            operator,
+            // A `ref`'s `name` is the INTERACTION it refers to (§17.7.4), never a
+            // guard, so it is not handed to the operand it would otherwise become the
+            // condition of. Every other operator's `name` is the first operand's
+            // guard, which is what `UmlFragmentElementModel.name` says it is.
+            operands: box
+                ? umlOperandBands(box, fragment.operands, operator === 'ref' ? '' : written)
+                : [{ y0: 0, y1: 0 }],
+            coveredLifelineIds: covered,
+        });
+    }
+    /** The smallest frame whose box holds a centre — most-nested wins. */
+    const frameOf = (element, frames, strictlyLarger = false) => {
+        const bounds = element.bounds;
+        if (!bounds)
+            return undefined;
+        const own = Math.max(0, bounds.w) * Math.max(0, bounds.h);
+        let best;
+        let bestArea = Number.POSITIVE_INFINITY;
+        for (const candidate of frames) {
+            const box = candidate.bounds;
+            if (candidate.id === element.id || !box)
+                continue;
+            if (!umlCentreInside(bounds, box))
+                continue;
+            const area = Math.max(0, box.w) * Math.max(0, box.h);
+            if (strictlyLarger && area <= own)
+                continue;
+            if (area < bestArea) {
+                best = candidate;
+                bestArea = area;
+            }
+        }
+        return best;
+    };
+    const partitionById = new Map(partitions.map(lane => [lane.id, lane]));
+    for (const node of activityNodes) {
+        const lane = frameOf(node, partitions);
+        if (!lane)
+            continue;
+        node.partitionId = lane.id;
+        partitionById.get(lane.id)?.nodeIds.push(node.id);
+    }
+    // §14.2.4's nesting: a composite state drawn inside a composite state. The
+    // strict-area test is what makes it an order rather than a cycle — the same
+    // guard `containerOf` holds for a package inside a package.
+    for (const region of regions) {
+        const parent = frameOf(region, regions, true);
+        if (parent)
+            region.parentId = parent.id;
+    }
+    for (const vertex of [...states, ...finalStates, ...pseudostates]) {
+        const region = frameOf(vertex, regions);
+        if (region)
+            vertex.regionId = region.id;
+    }
+    // Each part of a node's group answers for the node — but only where the group
+    // holds exactly one. See the docblock.
+    for (const group of groups) {
+        const inside = group.childIds.filter(id => artefactOf.has(id));
+        if (inside.length !== 1)
+            continue;
+        const artefact = artefactOf.get(inside[0]);
+        artefactOf.set(group.id, artefact);
+        for (const childId of group.childIds) {
+            if (!artefactOf.has(childId))
+                artefactOf.set(childId, artefact);
+        }
+    }
+    const relations = [];
+    /** §17.4's arrows, with the height each was drawn at. See {@link UmlMessage}. */
+    const messages = [];
+    for (const connector of connectors) {
+        const from = connector.source?.id;
+        const to = connector.target?.id;
+        const source = from ? artefactOf.get(from) : undefined;
+        const target = to ? artefactOf.get(to) : undefined;
+        // ── Is this line on THIS sheet at all? ───────────────────────────────
+        //
+        // The element list is the whole surface, not one frame's worth of it, so
+        // every connector of every diagram arrives here. A connector has no centre
+        // of its own until the router has run — its bound is derived from the path
+        // between its two ends, and a freshly loaded document answers `[0,0,0,0]` —
+        // so the reading that decides membership is its ENDS: a line belongs to this
+        // sheet when at least one of them resolves to an artefact of it. Only where
+        // neither does is the connector's own box asked, which catches the one case
+        // the ends cannot — a line the author drew on this sheet and attached to
+        // nothing.
+        //
+        // Without this test a board with two frames warned twice on every export
+        // about connectors that are perfectly drawn on the OTHER sheet (the
+        // tranche-F recette's finding): the ends resolved on neither diagram's
+        // `artefactOf`, so each export claimed the other's lines were dangling.
+        if (!source && !target && !onSheet(connector))
+            continue;
+        const kind = connector.role
+            ? RELATION_OF_ROLE.get(connector.role)
+            : undefined;
+        if (!kind) {
+            // A connector the author drew between two UML artefacts and never typed.
+            if (source && target) {
+                warnings.push('A connector between two UML elements carries no relationship type, so it is not in the file. Redraw it with one of the UML relationship tools.');
+            }
+            continue;
+        }
+        if (!source || !target) {
+            warnings.push(`A ${kind} could not be written: one of its ends is not on this diagram.`);
+            continue;
+        }
+        const label = umlTierText(connector.text);
+        // §11.5.4's adornments, read off the two per-end labels ADR 0020 added to
+        // the connector. Parsed only where the clause applies; kept verbatim
+        // everywhere else — see {@link UmlRelation.sourceEnd}.
+        const endOf = (text) => {
+            const raw = umlTierText(text);
+            if (!raw)
+                return undefined;
+            return ADORNED_RELATION_KINDS.has(kind) ? parseEndLabel(raw) : { raw };
+        };
+        const sourceEnd = endOf(connector.sourceLabel);
+        const targetEnd = endOf(connector.targetLabel);
+        relations.push({
+            kind,
+            sourceId: source,
+            targetId: target,
+            ...(label ? { label } : {}),
+            ...(sourceEnd ? { sourceEnd } : {}),
+            ...(targetEnd ? { targetEnd } : {}),
+        });
+        if (MESSAGE_KINDS.has(kind)) {
+            messages.push({
+                id: connector.id,
+                kind: kind,
+                sourceId: source,
+                targetId: target,
+                ...(label ? { label } : {}),
+                y: umlMessageHeight(connector, from ? boxOfElement.get(from) : undefined, to ? boxOfElement.get(to) : undefined),
+            });
+        }
+    }
+    // §17.4.4: "every line fragment is either horizontal or downwards" — the
+    // vertical axis is time, so the ORDER is what every writer needs and the
+    // height is what the canvas stated. Sorted once, here, with document order
+    // breaking a tie: two messages drawn at exactly the same height are two the
+    // author did not order, and a sort that reordered them on every export would
+    // make a golden file flap.
+    messages.sort((a, b) => a.y - b.y);
+    const kind = diagramKind;
+    const name = umlTierText(diagram.name);
+    const heading = typeof diagram.heading === 'string' && diagram.heading
+        ? diagram.heading
+        : `${UML_DIAGRAM_KIND_TAG[kind] ?? kind} ${name}`.trim();
+    // ── The two behaviours, assembled ─────────────────────────────────────
+    //
+    // The edges are PROJECTED from `relations` rather than read again: one pass
+    // over the connectors resolved every end, applied every attribution rule and
+    // raised every warning, and a second pass could only disagree with it. What is
+    // added here is the LABEL grammar — §15.2.4's guard and weight, §14.2.4.8's
+    // triggers, guard and effect — which is the one thing a flow says that a
+    // structural relationship does not.
+    const activityEdges = [];
+    const transitions = [];
+    for (const relation of relations) {
+        if (relation.kind === 'control-flow' || relation.kind === 'object-flow') {
+            const annotations = parseActivityEdge(relation.label);
+            activityEdges.push({
+                kind: relation.kind,
+                sourceId: relation.sourceId,
+                targetId: relation.targetId,
+                ...annotations,
+            });
+        }
+        else if (relation.kind === 'transition') {
+            const label = parseTransition(relation.label);
+            transitions.push({
+                sourceId: relation.sourceId,
+                targetId: relation.targetId,
+                ...label,
+            });
+        }
+    }
+    // A sheet holds a behaviour when it holds a GLYPH of it or a LINE of it: an
+    // author who has drawn two arrows and no boxes yet has still said something,
+    // and a writer that dropped it would lose the drawing rather than summarise
+    // it. A sheet holding neither contributes an empty list and neither writer
+    // emits a word.
+    const activities = activityNodes.length > 0 ||
+        activityEdges.length > 0 ||
+        partitions.length > 0
+        ? [
+            {
+                id: diagram.id,
+                name,
+                nodes: activityNodes,
+                edges: activityEdges,
+                partitions,
+            },
+        ]
+        : [];
+    const interactions = lifelines.length > 0 ||
+        messages.length > 0 ||
+        fragments.length > 0 ||
+        executions.length > 0 ||
+        destructions.length > 0
+        ? [
+            {
+                id: diagram.id,
+                name,
+                lifelines,
+                messages,
+                fragments,
+                executions,
+                destructions,
+            },
+        ]
+        : [];
+    const stateMachines = states.length > 0 ||
+        finalStates.length > 0 ||
+        pseudostates.length > 0 ||
+        transitions.length > 0 ||
+        regions.length > 0
+        ? [
+            {
+                id: diagram.id,
+                name,
+                regions,
+                states,
+                finalStates,
+                pseudostates,
+                transitions,
+            },
+        ]
+        : [];
+    return {
+        diagram: {
+            id: diagram.id,
+            kind,
+            name,
+            heading,
+            ...(frame ? { bounds: frame } : {}),
+        },
+        classifiers,
+        packages,
+        actors,
+        useCases,
+        subjects: subjectBoxes,
+        notes,
+        components,
+        ports,
+        artifacts,
+        nodes: deploymentNodes,
+        activities,
+        stateMachines,
+        interactions,
+        relations,
+        warnings,
+    };
+}
+/**
+ * The HEIGHT one message was drawn at — §17.4.4's whole statement about time.
+ *
+ * Read off the connector's stored END POSITIONS first, and that is the point of
+ * the function: a connector's own bound is DERIVED by the router from the path
+ * between its ends, and a freshly loaded document answers `[0,0,0,0]` until
+ * something paints. A `position` is in the store, so an export run against a
+ * document nobody has opened orders the conversation exactly as an export run
+ * against a board on screen does.
+ *
+ * Both ends when both are anchored, because §17.4.4 draws a message as a
+ * horizontal line and the two ends agree; the midpoint is what a message drawn
+ * slightly sloping means. One end when only one is anchored. The connector's own
+ * box when neither is — a message the author dragged onto empty canvas — and
+ * zero when there is nothing at all to read, which puts it first and says so by
+ * being obviously at the top.
+ */
+function umlMessageHeight(connector, from, to) {
+    const at = (end, box) => {
+        const t = end?.position?.[1];
+        if (!box || typeof t !== 'number' || !Number.isFinite(t))
+            return undefined;
+        return box.y + t * box.h;
+    };
+    const head = at(connector.source, from);
+    const tail = at(connector.target, to);
+    if (head !== undefined && tail !== undefined)
+        return (head + tail) / 2;
+    if (head !== undefined)
+        return head;
+    if (tail !== undefined)
+        return tail;
+    const bounds = umlBoundsOf(connector);
+    if (bounds && (bounds.w !== 0 || bounds.h !== 0)) {
+        return bounds.y + bounds.h / 2;
+    }
+    return 0;
+}
+/**
+ * Which entry comes first when two were drawn at exactly the same height.
+ *
+ * Only a hand-drawn board ever ties — an invented layout gives every event a
+ * slot of its own — and the order is the one a reader would write the lines in:
+ * the fragment that CONTAINS the moment opens first, then the arrow, then the
+ * bar it starts, then the bar it ends, and last the cross that ends the
+ * participant.
+ */
+const TIMELINE_RANK = {
+    fragment: 0,
+    message: 1,
+    'execution-start': 2,
+    'execution-finish': 3,
+    destruction: 4,
+};
+/**
+ * One Interaction as the ordered, nested account of what happens on it — the
+ * reading BOTH writers take, so that a `.puml` and an XMI file can never
+ * disagree about the order of a conversation.
+ *
+ * ## What decides that something is INSIDE a fragment
+ *
+ * Two things, and both are what §17.6.4 draws: the moment falls inside the
+ * fragment's box VERTICALLY, and the fragment COVERS the lifeline it happens on
+ * ({@link UmlCombinedFragment.coveredLifelineIds}). The second is what stops an
+ * `alt` drawn over two of five participants from swallowing a message exchanged
+ * between the other three at the same height — which a y-only test would, and
+ * which would put an arrow in a branch nobody drew it in.
+ *
+ * The innermost matching fragment wins, measured by AREA, exactly as `umlHostOf`
+ * and `containerOf` decide every other containment in this framework.
+ *
+ * Pure and total: every message, bar and cross of the interaction comes back
+ * exactly once, whether it landed in a fragment or at the top level.
+ */
+export function umlInteractionTimeline(interaction) {
+    /**
+     * The spine an end of a message is on.
+     *
+     * A message end names a LIFELINE, an execution bar or a destruction cross
+     * (§17.4.4 attaches a MessageEnd to an occurrence, and the canvas draws all
+     * three), and only a lifeline id is in a fragment's `coveredLifelineIds`. So
+     * the other two are resolved to the spine they sit on before containment is
+     * measured — without it a delete message is read as happening on a spine no
+     * fragment covers, and every `destroy` drawn inside an `opt` is written
+     * outside it, leaving the fragment empty.
+     */
+    const lifelineOfMark = new Map([
+        ...interaction.executions.map(execution => [execution.id, execution.lifelineId]),
+        ...interaction.destructions.map(destruction => [destruction.id, destruction.lifelineId]),
+    ]);
+    const spineOf = (id) => lifelineOfMark.has(id) ? lifelineOfMark.get(id) : id;
+    const covers = new Map(interaction.fragments.map(fragment => [
+        fragment.id,
+        new Set(fragment.coveredLifelineIds),
+    ]));
+    const areaOf = (fragment) => fragment.bounds
+        ? Math.max(0, fragment.bounds.w) * Math.max(0, fragment.bounds.h)
+        : Number.POSITIVE_INFINITY;
+    /**
+     * The innermost fragment a moment on these spines falls in.
+     *
+     * `exclude` is the fragment being placed itself, so that a fragment cannot
+     * claim to contain itself; a fragment nested in another is placed against the
+     * outer one by its own top edge.
+     */
+    const fragmentAt = (y, spines, exclude) => {
+        let best;
+        let bestArea = Number.POSITIVE_INFINITY;
+        for (const fragment of interaction.fragments) {
+            if (fragment === exclude || !fragment.bounds)
+                continue;
+            const box = fragment.bounds;
+            if (y < box.y || y > box.y + box.h)
+                continue;
+            if (exclude?.bounds && areaOf(fragment) <= areaOf(exclude))
+                continue;
+            const covered = covers.get(fragment.id);
+            const named = spines.filter((id) => Boolean(id));
+            // A fragment covering NO lifeline of this moment is a rectangle drawn
+            // beside the conversation, not round it.
+            if (named.length > 0 && !named.every(id => covered.has(id)))
+                continue;
+            const area = areaOf(fragment);
+            if (area < bestArea ||
+                (area === bestArea && best && fragment.id < best.id)) {
+                best = fragment;
+                bestArea = area;
+            }
+        }
+        return best;
+    };
+    /** Which operand band of a fragment holds this height — the last that opens. */
+    const bandAt = (fragment, y) => {
+        let index = 0;
+        for (const [at, operand] of fragment.operands.entries()) {
+            if (y >= operand.y0)
+                index = at;
+        }
+        return index;
+    };
+    const built = new Map();
+    for (const fragment of interaction.fragments) {
+        built.set(fragment.id, {
+            at: 'fragment',
+            y: fragment.bounds ? fragment.bounds.y : 0,
+            fragment,
+            operands: fragment.operands.map(operand => ({ operand, entries: [] })),
+        });
+    }
+    const root = [];
+    const place = (entry, spines, self) => {
+        const host = fragmentAt(entry.y, spines, self);
+        if (!host) {
+            root.push(entry);
+            return;
+        }
+        const container = built.get(host.id);
+        const band = container.operands[bandAt(host, entry.y)];
+        if (band)
+            band.entries.push(entry);
+        else
+            root.push(entry);
+    };
+    // Outermost first, so a nested fragment's own container already exists when
+    // the fragments inside it are placed. Ordering by area is what makes that
+    // true whatever order the canvas was walked in.
+    for (const fragment of [...interaction.fragments].sort((a, b) => areaOf(b) - areaOf(a))) {
+        place(built.get(fragment.id), fragment.coveredLifelineIds, fragment);
+    }
+    for (const message of interaction.messages) {
+        place({ at: 'message', y: message.y, message }, [
+            spineOf(message.sourceId),
+            spineOf(message.targetId),
+        ]);
+    }
+    for (const execution of interaction.executions) {
+        place({ at: 'execution-start', y: execution.y0, execution }, [
+            execution.lifelineId,
+        ]);
+        place({ at: 'execution-finish', y: execution.y1, execution }, [
+            execution.lifelineId,
+        ]);
+    }
+    for (const destruction of interaction.destructions) {
+        place({ at: 'destruction', y: destruction.y, destruction }, [
+            destruction.lifelineId,
+        ]);
+    }
+    const order = (entries) => {
+        const sorted = [...entries].sort((a, b) => a.y - b.y || TIMELINE_RANK[a.at] - TIMELINE_RANK[b.at]);
+        for (const entry of sorted) {
+            if (entry.at !== 'fragment')
+                continue;
+            for (const band of entry.operands)
+                band.entries = order(band.entries);
+        }
+        return sorted;
+    };
+    return order(root);
+}
+/**
+ * One line of an object's compartment as a SLOT.
+ *
+ * Read through {@link parseProperty} rather than by splitting on `=`, so that
+ * `stock : Integer = 3` — a slot an author wrote the feature's type on — gives
+ * the same `stock = 3` a bare `stock = 3` does. The type is dropped because a
+ * slot does not declare one: §11.6.4's compartment gives VALUES to features the
+ * Classifier already typed.
+ */
+function slotOf(line) {
+    const property = parseProperty(line);
+    return {
+        name: property.name,
+        ...(property.defaultValue ? { value: property.defaultValue } : {}),
+    };
+}