@formicoidea/labre-framework-uml 0.42.0

package/dist/model.d.ts

@@ -0,0 +1,862 @@
+import { type UmlDiagramKind, type UmlFragmentOperand, type UmlFragmentOperator, type UmlNodeKind } from '@formicoidea/labre-core/model';
+import { type UmlBox, type UmlComponent, type UmlComponentElement, type UmlComponentGroup } from './component.js';
+import { type UmlAssociationEnd, type UmlOperation, type UmlProperty } from './grammar.js';
+/**
+ * The neutral intermediate representation one UML diagram exports through.
+ *
+ * ## Why there is an IR at all
+ *
+ * Two writers — PlantUML and XMI — and one canvas. Without a model in between,
+ * each writer would have to know that a class's name lives in a grouped text
+ * element with the role `uml:name`, that its attributes are a second one, that a
+ * connector's ends may land on the group rather than on the shape, and that a
+ * package contains what its box contains. Two copies of that reading is two
+ * copies that drift, and the drift shows up as two files that disagree about the
+ * same drawing.
+ *
+ * So the canvas is read ONCE, here, and the writers take records. It is also
+ * what makes them testable with literals: a golden XMI test needs a model, not a
+ * surface.
+ *
+ * ## Pure
+ *
+ * Elements in, records out. No `std`, no DOM, no clock, no randomness — the
+ * discipline `docs/adr/0012` P3 sets for every interchange function, and the
+ * reason {@link umlModelFrom} takes plain structural records
+ * ({@link UmlSourceElement}) rather than element models: the same function runs
+ * against a live surface and against six object literals in a spec.
+ */
+/**
+ * The shape of an element as this module reads it.
+ *
+ * Structural, and deliberately so: every field is one a real
+ * `GfxPrimitiveElementModel` carries, and every field is optional, so a test can
+ * hand over `{ id, type, kind, xywh }` and get the same answer a surface does.
+ * `text` and `name` are `unknown` because on a live element they are a `Y.Text`
+ * and in a spec they are a string, and nothing here has any business knowing
+ * which — both go through `umlTierText`, which stringifies whatever it is given.
+ * That is also what keeps this file free of a Yjs import.
+ */
+export interface UmlSourceElement extends UmlComponentElement {
+    /** `'umlDiagram'`, `'umlNode'`, `'umlSubject'`, `'connector'`, `'text'`, … */
+    type?: string;
+    /** `UmlNodeKind` on a node, `UmlDiagramKind` on a frame. */
+    kind?: string;
+    name?: unknown;
+    heading?: unknown;
+    /** Which way a `umlPartition`'s band runs (§15.6.4). */
+    orientation?: string;
+    xywh?: string;
+    deserializedXYWH?: readonly number[];
+    elementBound?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** A group's members. */
+    childIds?: readonly string[];
+    /**
+     * A connector's ends.
+     *
+     * `position` is the RELATIVE point the end is anchored at on the element it
+     * touches — `[0.5, 0.5]` for a centre anchor, `[0, 0.35]` for a message
+     * attached a third of the way down a lifeline's left edge. Read for one thing
+     * only, and it is the thing a sequence diagram is made of: §17.4.4 says the
+     * HEIGHT an arrow is drawn at is WHEN it happens, and that height is stored
+     * here rather than derived — a connector's own bound is computed by the router
+     * and reads `[0,0,0,0]` on a freshly loaded document.
+     */
+    source?: {
+        id?: string;
+        position?: readonly number[];
+    } | null;
+    target?: {
+        id?: string;
+        position?: readonly number[];
+    } | null;
+    /** A `umlFragment`'s interaction operator (§17.6.4). */
+    operator?: string;
+    /** A `umlFragment`'s operand bands, top to bottom (§17.6.4). */
+    operands?: readonly UmlFragmentOperand[];
+    /**
+     * The two PER-END labels of a connector (ADR 0020), beside `text`.
+     *
+     * `unknown` for the reason {@link UmlSourceElement.name} is: a live connector
+     * holds a `Y.Text` and a spec hands over a string, and both go through
+     * `umlTierText`.
+     */
+    sourceLabel?: unknown;
+    targetLabel?: unknown;
+}
+/** A slot of an InstanceSpecification — `attribute = value` (§11.6.4). */
+export interface UmlSlot {
+    name: string;
+    /** Absent when the author named a feature and gave it no value. */
+    value?: string;
+}
+/** What every drawn artefact states, whatever kind it is. */
+export interface UmlNodeBase {
+    /** The surface element's id — what a relation's ends resolve to. */
+    id: string;
+    name: string;
+    /** Annex C labels read off the name compartment, in order. */
+    keywords: string[];
+    /** `{abstract}` was written on it (§9.2.4). */
+    isAbstract: boolean;
+    /** Where it is drawn — what package and subject nesting is decided by. */
+    bounds?: UmlBox;
+}
+/** A Class, an Interface, an Enumeration or an InstanceSpecification. */
+export interface UmlClassifier extends UmlNodeBase {
+    kind: Extract<UmlNodeKind, 'class' | 'interface' | 'enumeration' | 'object'>;
+    /** The attribute compartment, parsed. Empty for an object. */
+    attributes: UmlProperty[];
+    /** The operation compartment, parsed. Empty for an object. */
+    operations: UmlOperation[];
+    /** The value compartment of an object. Empty for the other three. */
+    slots: UmlSlot[];
+    /**
+     * The compartments as the author TYPED them — trimmed, blanks and elision
+     * markers dropped, and otherwise untouched.
+     *
+     * Carried beside the parsed forms because one of the two writers wants each.
+     * XMI needs the structure: it has a slot for a visibility, a type and a
+     * multiplicity and nothing to do with a line. PlantUML's member syntax IS
+     * §9.5.4's own notation, so re-spelling a parsed property for it could only
+     * lose what the parser did not model — a constraint, an unusual modifier, a
+     * qualified redefinition. Both readings of the same compartment, stated once
+     * here rather than re-derived in two files.
+     */
+    lines: {
+        attributes: string[];
+        operations: string[];
+    };
+    /**
+     * The Classifier an object is an instance OF — the `Class` of
+     * `object : Class` (§11.6.4). Objects only, and absent when the author wrote
+     * a bare instance name.
+     */
+    instanceOf?: string;
+}
+/** A Package (§12.2), an Actor or a UseCase (§18.1) — a named box. */
+export type UmlPackageNode = UmlNodeBase;
+export type UmlActorNode = UmlNodeBase;
+export type UmlUseCaseNode = UmlNodeBase;
+/**
+ * A Port (§11.3) — the small square on an EncapsulatedClassifier's boundary.
+ *
+ * `ownerId` is the surface id of the component (or the node) the square is drawn
+ * ON, and it is GEOMETRY rather than a stored link: §11.3.4 says the symbol "may
+ * be placed either overlapping the boundary of the rectangle symbol denoting
+ * that EncapsulatedClassifier or it may be shown inside the rectangle symbol",
+ * and a canvas has no other statement to read. See {@link umlHostOf} for the
+ * reading and for its tolerance.
+ *
+ * Absent when the author has drawn a port beside every box, which is a port
+ * belonging to nothing — the file writes it nowhere rather than guessing an
+ * owner, and the drawing keeps it.
+ */
+export interface UmlPort extends UmlNodeBase {
+    ownerId?: string;
+}
+/**
+ * A Component (§11.6) — the classifier rectangle with the two-tab icon.
+ *
+ * `provided` and `required` are the NAMES read off the lollipops and sockets
+ * drawn against it, not references: §10.4.4 draws a provided Interface as a
+ * circle "labeled with the name of the Interface, attached by a solid line to
+ * the BehavioredClassifier that realizes this Interface", and on this canvas the
+ * glyph carries its own `uml:label` and nothing else. The names are what both
+ * writers need — XMI mints a `uml:Interface` per name, PlantUML declares one —
+ * and what neither can get from an id, because the glyph IS the interface as far
+ * as the drawing is concerned.
+ *
+ * `ports` are the squares on its border, resolved the same geometric way.
+ */
+export interface UmlComponentNode extends UmlNodeBase {
+    ports: UmlPort[];
+    /** Interface names read off the lollipops touching this component. */
+    provided: string[];
+    /** Interface names read off the sockets touching this component. */
+    required: string[];
+}
+/** An Artifact (§19.3) — the `«artifact»` rectangle with the document icon. */
+export type UmlArtifactNode = UmlNodeBase;
+/**
+ * A Node, a Device or an ExecutionEnvironment (§19.4) — the perspective cube.
+ *
+ * ONE record with a `kind` discriminant rather than three lists, because §19.4.2
+ * makes Device and ExecutionEnvironment specializations of Node and §19.4.4
+ * draws all three as the same cube: the keyword is the difference, and both
+ * writers need exactly that — an `xmi:type` and a PlantUML stereotype.
+ */
+export interface UmlDeploymentNode extends UmlNodeBase {
+    kind: Extract<UmlNodeKind, 'node' | 'device' | 'execution-environment'>;
+}
+/** The subject of a use case diagram — the rectangle the cases sit in. */
+export type UmlSubjectBox = UmlNodeBase;
+/** A Comment (Annex A) — prose, kept whole. */
+export interface UmlNote extends UmlNodeBase {
+    /** The note's text, verbatim: a note is prose, not a name compartment. */
+    body: string;
+}
+/**
+ * The relationships phase 1 draws — the local half of each `uml:…` edge role.
+ *
+ * A closed union rather than an open string, because every writer maps it
+ * TOTALLY: a `Record<UmlRelationKind, …>` in `plantuml.ts` and an exhaustive
+ * `switch` in `xmi.ts` both fail the build the day a tenth relationship is drawn
+ * with nothing to write it as. That failure is cheap here and expensive in a
+ * file somebody exported.
+ */
+export type UmlRelationKind = 'association' | 'aggregation' | 'composition' | 'generalization' | 'realization' | 'dependency' | 'anchor' | 'include' | 'extend' | 'deploy' | 'manifest' | 'communication-path' | 'control-flow' | 'object-flow' | 'transition' | 'message-sync' | 'message-async' | 'message-reply' | 'message-create' | 'message-delete';
+/** One connector, once both of its ends are known artefacts of this diagram. */
+export interface UmlRelation {
+    kind: UmlRelationKind;
+    /**
+     * The SUBJECT of the sentence the edge's direction states (the role table in
+     * `roles.ts`): the specific classifier of a generalization, the WHOLE of an
+     * aggregation, the base UseCase of an include, the extending UseCase of an
+     * extend.
+     */
+    sourceId: string;
+    targetId: string;
+    /** The connector's own centre text, when it carries one. */
+    label?: string;
+    /**
+     * What is written beside the SOURCE end of the line — §11.5.4's adornments.
+     *
+     * Present whenever the connector carries an end label at all, whatever the
+     * relationship is. On the four kinds §11.5.4 governs
+     * ({@link ADORNED_RELATION_KINDS}) it is PARSED — a multiplicity, a role name,
+     * a visibility glyph; on every other kind only
+     * {@link UmlAssociationEnd.raw} is filled, because a multiplicity beside a
+     * generalization is not a multiplicity of anything and writing one into a file
+     * would state a fact the metamodel has nowhere to hold. Carrying the raw text
+     * regardless is what keeps the round trip lossless: the author's words come
+     * back on the board even where no writer can spell them.
+     */
+    sourceEnd?: UmlAssociationEnd;
+    /** What is written beside the TARGET end — see {@link sourceEnd}. */
+    targetEnd?: UmlAssociationEnd;
+}
+/**
+ * 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 declare const ADORNED_RELATION_KINDS: ReadonlySet<UmlRelationKind>;
+/** The ten glyphs an `act` sheet draws — §15.3.4, §15.4.4, §16.3.4, §16.10.4. */
+export type UmlActivityNodeKind = Extract<UmlNodeKind, 'action' | 'initial' | 'activity-final' | 'flow-final' | 'decision' | 'fork' | 'object-node' | 'send-signal' | 'accept-event' | 'time-event'>;
+/**
+ * One node of an Activity — the glyph, its words, and the lane it is drawn in.
+ *
+ * ONE record with a `kind` discriminant rather than ten lists, for the reason
+ * {@link UmlDeploymentNode} gives: §15.7 makes all ten ActivityNodes and both
+ * writers need exactly the discriminant — an `xmi:type` and a PlantUML
+ * stereotype. A list per glyph would be ten fields the writers would have to
+ * concatenate back into one traversal order.
+ */
+export interface UmlActivityNode extends UmlNodeBase {
+    kind: UmlActivityNodeKind;
+    /**
+     * The surface id of the `umlPartition` whose box holds this node's centre —
+     * §15.6.4's swimlane, read at EXPORT time from geometry and never stored.
+     *
+     * The same reading {@link UmlPort.ownerId} gets, and for the same reason: a
+     * partition is a band drawn across the sheet, membership is which band a glyph
+     * sits in, and a canvas holds no second statement about it. Absent for a node
+     * drawn between the lanes, or on a sheet with no lanes at all — which is most
+     * of them.
+     */
+    partitionId?: string;
+}
+/** One ActivityEdge — the arrow, and the three things §15.2.4 writes on it. */
+export interface UmlActivityEdge {
+    /** §15.7.9 / §15.7.11 — which of the two kinds of token travels. */
+    kind: Extract<UmlRelationKind, 'control-flow' | 'object-flow'>;
+    sourceId: string;
+    targetId: string;
+    /** The edge's own name, "notated near the arrow". */
+    name?: string;
+    /** The `[…]` guard, without its brackets — §15.2.4's own notation. */
+    guard?: string;
+    /** `{weight = …}`'s value, as written — see {@link UmlActivityEdgeLabel}. */
+    weight?: string;
+}
+/** An ActivityPartition (§15.6) — the swimlane, and what is drawn in it. */
+export interface UmlPartition extends UmlNodeBase {
+    /** Which way the band runs. A column unless the author turned it. */
+    orientation: 'vertical' | 'horizontal';
+    /**
+     * The activity nodes whose centres it holds, in document order.
+     *
+     * Listed on the partition AS WELL AS named by each node's
+     * {@link UmlActivityNode.partitionId}, and the duplication is the one
+     * {@link UmlModel.ports} already explains: the XMI writer walks the lane (an
+     * `ActivityPartition` carries `node` idrefs, so it needs the list) while a
+     * reader asking which lane one action is in must not have to scan every lane
+     * to find out. Both readings are built from one pass, so they cannot disagree.
+     */
+    nodeIds: string[];
+}
+/**
+ * One Activity — the whole of what an `act` sheet says.
+ *
+ * A frame is ONE Activity: §15.2.4 draws the border and the name in the upper
+ * left corner, Annex A replaces that border with the diagram frame, and that is
+ * exactly the frame this model was read off. So the id and the name are the
+ * sheet's own, and a second activity on one canvas is a second frame — the same
+ * reading ADR 0017 makes about every other UML sheet.
+ */
+export interface UmlActivity {
+    /** The diagram frame's surface id — the Activity IS the sheet. */
+    id: string;
+    name: string;
+    nodes: UmlActivityNode[];
+    edges: UmlActivityEdge[];
+    partitions: UmlPartition[];
+}
+/** The nine glyphs §14.2.4 routes transitions through. */
+export type UmlPseudostateKind = Extract<UmlNodeKind, 'initial' | 'choice' | 'junction' | 'shallow-history' | 'deep-history' | 'entry-point' | 'exit-point' | 'terminate' | 'fork'>;
+/** A Region (§14.2.4) — the composite state, drawn as a box round its parts. */
+export interface UmlRegion extends UmlNodeBase {
+    /**
+     * The region this one is drawn inside — §14.2.4's nested composite state.
+     *
+     * Geometry, most-nested first, exactly as a package inside a package is read
+     * (`xmi.ts`'s `containerOf`). Absent for a region at the top level of the
+     * sheet, which is where most of them are.
+     */
+    parentId?: string;
+}
+/** A State (§14.2.4.4) — the rounded box and its internal activities. */
+export interface UmlState extends UmlNodeBase {
+    /** `entry / …` lines, in order, as the expressions alone. */
+    entry: string[];
+    /** `do / …` lines — the metamodel's `doActivity`. */
+    doActivity: string[];
+    /** `exit / …` lines. */
+    exit: string[];
+    /**
+     * Every line of the compartment that is NONE of the three — an internal
+     * transition (§14.2.4.4's second compartment), a constraint, a note to self.
+     *
+     * Carried rather than dropped for the reason {@link UmlClassifier.lines}
+     * exists: the author typed it, so something has to be able to write it back,
+     * and a writer that silently lost a compartment would be the worst kind of
+     * lossy export. Neither writer has a metamodel slot for it today; PlantUML
+     * prints it as a state line.
+     */
+    lines: string[];
+    /** The composite state whose box holds its centre — {@link UmlRegion}. */
+    regionId?: string;
+}
+/** A FinalState (§14.2.4.5) — the bullseye a machine stops at. */
+export interface UmlFinalState extends UmlNodeBase {
+    regionId?: string;
+}
+/** A Pseudostate (§14.2.4.6) — a vertex that routes rather than one that is. */
+export interface UmlPseudostate extends UmlNodeBase {
+    kind: UmlPseudostateKind;
+    regionId?: string;
+}
+/** One Transition (§14.2.4.8) — its two ends and its label, parsed. */
+export interface UmlTransition {
+    sourceId: string;
+    targetId: string;
+    /** `<trigger> [',' <trigger>]*`, verbatim and in order. */
+    triggers: string[];
+    /** The `[…]` guard, without its brackets. */
+    guard?: string;
+    /** The `/ <behavior-expression>` effect, as written. */
+    effect?: string;
+}
+/**
+ * One StateMachine — the whole of what an `stm` sheet says.
+ *
+ * {@link UmlActivity}'s twin, and it carries its vertices in FOUR lists rather
+ * than one discriminated list because the metamodel does: a State owns
+ * behaviours and regions, a FinalState owns neither and forbids both
+ * (§14.5.11.4), and a Pseudostate is a `kind` attribute on one metaclass. Three
+ * different `xmi:type`s with three different shapes is three lists; ten
+ * identically shaped ActivityNodes is one.
+ */
+export interface UmlStateMachine {
+    /** The diagram frame's surface id — the StateMachine IS the sheet. */
+    id: string;
+    name: string;
+    /** The composite states, outermost and nested alike. */
+    regions: UmlRegion[];
+    states: UmlState[];
+    finalStates: UmlFinalState[];
+    pseudostates: UmlPseudostate[];
+    transitions: UmlTransition[];
+}
+/**
+ * §17.4.3's `messageSort`, as the five arrows an `sd` sheet is drawn with.
+ *
+ * A projection of {@link UmlRelationKind} rather than a union of its own, for
+ * the reason {@link UmlActivityEdge.kind} is one: a message IS a connector on
+ * the canvas, read off the same role table in the same pass, and two spellings
+ * of the same five words would be two things to keep in step.
+ */
+export type UmlMessageKind = Extract<UmlRelationKind, 'message-sync' | 'message-async' | 'message-reply' | 'message-create' | 'message-delete'>;
+/**
+ * A Lifeline (§17.3) — the participant column: a named head over a dashed
+ * spine.
+ *
+ * `name` and `type` are the two halves of §17.3.4's `<name> : <Type>`, split by
+ * `parseLifelineIdent` — the same grammar `keywords.ts` seeds a fresh head
+ * with. `type` is absent when the author wrote a bare participant name, which
+ * is most of them.
+ */
+export interface UmlLifeline extends UmlNodeBase {
+    /** The Classifier this participant is an instance of (§17.3.4). */
+    type?: string;
+}
+/**
+ * One Message (§17.4) — its two ends, its label, and WHEN it happens.
+ *
+ * ## Why `y` is on the record and the list is sorted by it
+ *
+ * Because on a sequence diagram the vertical axis IS time (§17.4.4: "every line
+ * fragment is either horizontal or downwards"), and every writer needs the
+ * order rather than the height: XMI serializes a pair of
+ * `MessageOccurrenceSpecification`s per message and an Interaction's `fragment`
+ * list is READ IN ORDER, PlantUML's whole syntax is one message per line top to
+ * bottom. So the canvas's one statement about sequence — the height an arrow was
+ * drawn at — is turned into an order here, once, and the writers take a list.
+ *
+ * `sourceId` and `targetId` are the ids the connector actually resolves to,
+ * which is a LIFELINE or an EXECUTION ({@link UmlExecution}): §17.4.4 draws an
+ * arrow onto the bar as readily as onto the spine, and a reading that snapped
+ * every end to a lifeline would lose which activation the author aimed at.
+ * A writer that needs the covering lifeline resolves it through
+ * {@link UmlExecution.lifelineId}.
+ */
+export interface UmlMessage {
+    /** The connector's own surface id — what a report names it by. */
+    id: string;
+    kind: UmlMessageKind;
+    sourceId: string;
+    targetId: string;
+    /** The connector's centre text: §17.4.4's message label, as written. */
+    label?: string;
+    /** The height it is drawn at — see the docblock. */
+    y: number;
+}
+/**
+ * One InteractionOperand (§17.6.4) — a horizontal band of a combined fragment,
+ * separated from the next by a dashed line.
+ *
+ * `guard` is §17.6.4's `[…]` InteractionConstraint WITHOUT its brackets, the
+ * same way {@link UmlActivityEdge.guard} and {@link UmlTransition.guard} carry
+ * theirs: the brackets are the notation's delimiter, and a writer that had to
+ * strip them would be parsing its own model. The canvas keeps them — they are
+ * what the author typed and what the renderer paints — and
+ * {@link umlGuardText} takes exactly one pair off on the way in here.
+ *
+ * `y0` and `y1` are the band's own top and bottom in canvas units, because that
+ * is what decides which messages are inside WHICH operand — an `alt`'s two
+ * branches are told apart by nothing else.
+ */
+export interface UmlInteractionOperand {
+    guard?: string;
+    y0: number;
+    y1: number;
+}
+/**
+ * A CombinedFragment (§17.6) — the rectangle with an operator in its corner —
+ * and, under the `ref` operator, §17.7's InteractionUse.
+ *
+ * ONE record for both, because the canvas draws one element for both
+ * (`UmlFragmentElementModel`): §17.7.4's InteractionUse is the same rectangle
+ * with the same pentagon, and every tool offers it from the same menu. The
+ * writers branch on `operator === 'ref'`, which is one line each.
+ *
+ * `name` is the fragment's own word — the first operand's guard on an `alt`,
+ * the referenced interaction's name on a `ref`.
+ *
+ * `coveredLifelineIds` is GEOMETRY, like every other membership in this file:
+ * a fragment covers the lifelines whose spine runs through it, because that is
+ * what §17.6.4 draws and a canvas holds no second statement about it.
+ */
+export interface UmlCombinedFragment extends UmlNodeBase {
+    operator: UmlFragmentOperator;
+    operands: UmlInteractionOperand[];
+    coveredLifelineIds: string[];
+}
+/**
+ * An ExecutionSpecification (§17.2.4) — the thin bar saying the participant is
+ * busy between two occurrences.
+ *
+ * `lifelineId` is the spine the bar sits ON, resolved by measuring
+ * ({@link umlLifelineAt}): a bar is a plain node and the canvas holds no
+ * parent link, exactly as a port's owner and a lollipop's component are read by
+ * measuring. Absent for a bar drawn off every spine — which is on the drawing
+ * and in no file.
+ */
+export interface UmlExecution extends UmlNodeBase {
+    lifelineId?: string;
+    /** The occurrence it starts at. */
+    y0: number;
+    /** The occurrence it finishes at. */
+    y1: number;
+}
+/** A DestructionOccurrenceSpecification (§17.2.4) — the X a lifeline ends at. */
+export interface UmlDestruction extends UmlNodeBase {
+    lifelineId?: string;
+    y: number;
+}
+/**
+ * One Interaction — the whole of what an `sd` sheet says.
+ *
+ * {@link UmlActivity}'s and {@link UmlStateMachine}'s twin, down to the reading
+ * that the FRAME IS THE INTERACTION: §17.2.4 draws the interaction as a
+ * rectangle with `sd <name>` in its corner, which is Annex A's frame, which is
+ * the frame this model was read off.
+ */
+export interface UmlInteraction {
+    /** The diagram frame's surface id — the Interaction IS the sheet. */
+    id: string;
+    name: string;
+    lifelines: UmlLifeline[];
+    /** ORDERED by `y`: top to bottom is earlier to later (§17.4.4). */
+    messages: UmlMessage[];
+    fragments: UmlCombinedFragment[];
+    executions: UmlExecution[];
+    destructions: UmlDestruction[];
+}
+/** One diagram, as everything the writers need and nothing else. */
+export interface UmlModel {
+    diagram: {
+        id: string;
+        kind: UmlDiagramKind;
+        name: string;
+        /** `<kind> <name>` — Annex A's frame heading. */
+        heading: string;
+        bounds?: UmlBox;
+    };
+    classifiers: UmlClassifier[];
+    packages: UmlPackageNode[];
+    actors: UmlActorNode[];
+    useCases: UmlUseCaseNode[];
+    subjects: UmlSubjectBox[];
+    notes: UmlNote[];
+    /** §11.6 — the component boxes, each carrying its ports and its interfaces. */
+    components: UmlComponentNode[];
+    /**
+     * §11.3 — every port on the sheet, whether or not it found a host.
+     *
+     * Listed here AS WELL AS under its component, and the duplication is on
+     * purpose: the XMI writer walks the components (a `uml:Port` is an
+     * `ownedAttribute`, so it has nowhere else to go) while a reader asking "how
+     * many ports are on this sheet" — a check, a count, a later rule — must not
+     * have to know that a hostless one is invisible from every component. The two
+     * readings hold the SAME record, so they cannot disagree.
+     */
+    ports: UmlPort[];
+    /** §19.3 — the artefacts. */
+    artifacts: UmlArtifactNode[];
+    /** §19.4 — the nodes, devices and execution environments. */
+    nodes: UmlDeploymentNode[];
+    /**
+     * §15.2 — the Activity this sheet draws, or nothing.
+     *
+     * A LIST holding zero or one entry rather than an optional field, and the
+     * shape is what makes both writers a loop instead of a branch: every other
+     * artefact on this model is a list, `for (const activity of model.activities)`
+     * reads identically to `for (const component of model.components)`, and a
+     * sheet that draws no flow contributes nothing without either writer testing
+     * for it. Populated when the sheet holds an activity NODE or an activity EDGE
+     * — a lone arrow is still something the author drew.
+     */
+    activities: UmlActivity[];
+    /** §14.2 — the StateMachine this sheet draws, or nothing. The same shape. */
+    stateMachines: UmlStateMachine[];
+    /** §17.2 — the Interaction this sheet draws, or nothing. The same shape. */
+    interactions: UmlInteraction[];
+    relations: UmlRelation[];
+    /**
+     * What the READING could not make sense of, one line each, in the user's
+     * words (`InterchangeExportResult.warnings`).
+     *
+     * Never an error and never noise: the two cases below are both a connector
+     * the author DREW that no file can carry, which is the one thing a user who
+     * clicked Export is entitled to be told about. A shape with no role, a
+     * neutral connector between two neutral shapes, a type name that names
+     * nothing on this sheet — none of those is warned about, because none of them
+     * is a statement the author made and lost (`docs/adr/0010`).
+     */
+    warnings: string[];
+}
+/**
+ * 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 declare function umlBoundsOf(element: UmlSourceElement): UmlBox | undefined;
+/** Inclusive containment of a box's CENTRE in another box. */
+export declare function umlCentreInside(inner: UmlBox, outer: UmlBox): boolean;
+/**
+ * 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 declare 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 declare function umlBoxGap(a: UmlBox, b: UmlBox): number;
+/**
+ * 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 declare function umlSheetOf(frame: UmlBox): UmlBox;
+/** The little {@link umlHostOf} needs to know about a candidate host. */
+export interface UmlHostCandidate {
+    id: string;
+    bounds?: UmlBox;
+}
+/**
+ * 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 declare function umlHostOf<T extends UmlHostCandidate>(glyph: UmlBox | undefined, hosts: readonly T[], tolerance?: number): T | undefined;
+/**
+ * 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 declare function umlSpineX(lifeline: UmlBox): number;
+/**
+ * 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 declare const UML_SPINE_TOLERANCE: number;
+/**
+ * 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 declare function umlLifelineAt<T extends UmlHostCandidate>(glyph: UmlBox | undefined, lifelines: readonly T[]): T | undefined;
+/**
+ * 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 declare function umlGuardText(written: string | undefined): string;
+export declare function umlOperandBands(box: UmlBox, operands: readonly UmlFragmentOperand[] | undefined, name: string): UmlInteractionOperand[];
+export interface UmlModelOptions {
+    /**
+     * Which words belong to which shape — `component.ts`'s
+     * {@link umlComponentSiblings}, injectable.
+     *
+     * Injectable rather than only imported so a caller can resolve a component
+     * some other way (a test with a hand-built resolution, a host that already
+     * holds the answer) without this module growing a second reading of a group.
+     * The default IS `umlComponentSiblings`, so nothing has two behaviours.
+     */
+    siblingsOf?: (group: UmlComponentGroup, elements: readonly UmlComponentElement[]) => UmlComponent;
+}
+/**
+ * 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 declare function umlModelFrom(diagram: UmlSourceElement, elements: readonly UmlSourceElement[], options?: UmlModelOptions): UmlModel;
+/**
+ * One thing that happens on a sequence sheet, at the height it happens at.
+ *
+ * A discriminated union over the five, and a TREE rather than a list: a combined
+ * fragment carries the entries drawn inside each of its operands, which is what
+ * §17.6.4 makes it — an `InteractionOperand` OWNS the fragments in its band, and
+ * PlantUML's `alt … else … end` is the same nesting spelled with keywords.
+ */
+export type UmlTimelineEntry = {
+    at: 'message';
+    y: number;
+    message: UmlMessage;
+} | {
+    at: 'execution-start';
+    y: number;
+    execution: UmlExecution;
+} | {
+    at: 'execution-finish';
+    y: number;
+    execution: UmlExecution;
+} | {
+    at: 'destruction';
+    y: number;
+    destruction: UmlDestruction;
+} | {
+    at: 'fragment';
+    y: number;
+    fragment: UmlCombinedFragment;
+    operands: UmlTimelineOperand[];
+};
+/** One operand's band and what is drawn in it. */
+export interface UmlTimelineOperand {
+    operand: UmlInteractionOperand;
+    entries: UmlTimelineEntry[];
+}
+/**
+ * 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 declare function umlInteractionTimeline(interaction: UmlInteraction): UmlTimelineEntry[];