@formicoidea/labre-framework-uml 0.59.0 → 0.60.0

package/dist/import.js

@@ -1,13 +1,10 @@
-import { connectorEndLabelBox, ConnectorMode, TextAlign, UML_FRAME_BAND_HEIGHT, UML_LIFELINE_HEAD, } from '@formicoidea/labre-core/model/headless';
+import { connectorEndLabelBox, UML_FRAME_BAND_HEIGHT, UML_LIFELINE_HEAD, } from '@formicoidea/labre-core/model/headless';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
-import { umlCompartmentBoxes, umlLabelRoleOf, } from './component.js';
-import { UML_BODY_FONT_SIZE, UML_DIAGRAM_BOX, UML_EDGE_WIDTH, UML_FRAGMENT_BOX, UML_INK, UML_NAME_FONT_SIZE, UML_NODE_BOX, UML_PARTITION_BOX, UML_REGION_BOX, UML_SUBJECT_BOX, } from './consts.js';
-import { UML_EDGE_STYLE } from './edge-styles.js';
+import { UML_DIAGRAM_BOX, UML_FRAGMENT_BOX, UML_NODE_BOX } from './consts.js';
 import { formatActivityEdgeLabel, formatEndLabel, formatTransitionLabel, } from './grammar.js';
-import { guillemets, UML_UNLABELLED_KINDS } from './keywords.js';
+import { guillemets } from './keywords.js';
 import { umlGuardText, } from './model.js';
-import { umlNameDecoration, umlNodeProps, umlTextProps } from './presets.js';
-import { UML_ROLE } from './roles.js';
+import { UML_FRAME_BOX, umlArtefactElements, umlConnectorProps, umlFrameProps, } from './presets.js';
 /**
  * The **one materializer** every UML importer ends on — a model in, the
  * serialized props of a board out (`docs/adr/0012`, P3).
@@ -30,11 +27,12 @@ import { UML_ROLE } from './roles.js';
  *
  * ## Never a size, never a colour, never a seed
  *
- * Every prop below comes out of {@link umlNodeProps}, {@link umlTextProps} and
- * {@link umlCompartmentBoxes} — the very three functions the creation site calls
- * (R17). Not one measurement is restated here, so an imported class and a drawn
- * one are the same element down to the stroke width, and a restyle that moves
- * the pack moves the import with it.
+ * Every artefact below comes out of {@link umlArtefactElements}, every frame
+ * out of {@link umlFrameProps} and every line out of {@link umlConnectorProps}
+ * — the very assembly the toolbar and the toolbox call (R17,
+ * `docs/adr/0045`). Not one measurement is restated here, so an imported class
+ * and a drawn one are the same element down to the stroke width, and a restyle
+ * that moves the pack moves the import with it.
  *
  * ## The two names an element carries, and they are not the same name
  *
@@ -362,38 +360,6 @@ function stateBodyText(state) {
         ...state.lines,
     ].join('\n');
 }
-/* ── What a draft is ──────────────────────────────────────────────────── */
-/**
- * The glyph kinds whose one tier is a `uml:name` rather than a `uml:label`.
- *
- * A transcription of `actions.ts`'s own `NAMED_GLYPHS`, kept here rather than
- * imported because that module reaches for the editor (`BlockStdScope`, the gfx
- * controller, the surface) and a reader must not: P3 is what lets labre-mcp call
- * this file with no DI in sight. `import.unit.spec.ts` re-runs the creation
- * commands against a recording surface and compares the tier roles, so the two
- * statements cannot drift in silence.
- */
-const NAMED_GLYPH_KINDS = new Set([
-    'package',
-    'note',
-    'node',
-    'device',
-    'execution-environment',
-]);
-/** The four background frames, and the box each is created at. */
-const FRAME_BOX = {
-    umlSubject: UML_SUBJECT_BOX,
-    umlPartition: UML_PARTITION_BOX,
-    umlRegion: UML_REGION_BOX,
-    umlFragment: UML_FRAGMENT_BOX,
-};
-/** The role each background frame carries — one table, read once below. */
-const FRAME_ROLE = {
-    umlSubject: UML_ROLE.subject,
-    umlPartition: UML_ROLE.partition,
-    umlRegion: UML_ROLE.region,
-    umlFragment: UML_ROLE.fragment,
-};
 /** Every artefact one model draws, in the order a reader should meet them. */
 function draftsOf(model) {
     const drafts = [];
@@ -413,7 +379,7 @@ function draftsOf(model) {
             element,
             name: record.name,
             ...(orientation ? { orientation } : {}),
-            size: FRAME_BOX[element],
+            size: UML_FRAME_BOX[element],
             ...(record.bounds ? { bounds: record.bounds } : {}),
         });
     };
@@ -591,7 +557,7 @@ function draftsOf(model) {
                         })),
                     }
                     : {}),
-                size: FRAME_BOX.umlFragment,
+                size: UML_FRAME_BOX.umlFragment,
                 ...(fragment.bounds ? { bounds: fragment.bounds } : {}),
             });
         }
@@ -940,12 +906,8 @@ export function umlElementsFromModel(models, options) {
         const dx = frame.x + UML_IMPORT_MARGIN - left;
         const dy = frame.y + UML_FRAME_BAND_HEIGHT + UML_IMPORT_CONTAINER_INSET - top;
         elements.push({
-            type: 'umlDiagram',
+            ...umlFrameProps('umlDiagram', { xywh: new Bound(frame.x, frame.y, frame.w, frame.h).serialize() }, { name: model.diagram.name, kind: model.diagram.kind }),
             id: mint(),
-            role: UML_ROLE.diagram,
-            name: model.diagram.name,
-            kind: model.diagram.kind,
-            xywh: new Bound(frame.x, frame.y, frame.w, frame.h).serialize(),
             ...payload(formatId, model.diagram.id),
         });
         /** The provisional name a relation's end resolves to. */
@@ -968,99 +930,44 @@ export function umlElementsFromModel(models, options) {
                     boxOf.set(draft.sourceId, placed);
                 }
                 elements.push({
-                    type: draft.element,
+                    ...umlFrameProps(draft.element, { xywh }, {
+                        name: draft.name ?? '',
+                        // The model defaults a band to vertical, and a creation that
+                        // restated the default would be a second place for it to be
+                        // changed.
+                        ...(draft.orientation === 'horizontal'
+                            ? { orientation: 'horizontal' }
+                            : {}),
+                        // §17.6.4's operator and its operand bands. `alt` is the model's
+                        // own default and is written all the same: unlike an
+                        // orientation, the operator IS the fragment, and a document that
+                        // left it out would be one whose pentagon depends on a default
+                        // nobody can see.
+                        ...(draft.operator ? { operator: draft.operator } : {}),
+                        ...(draft.operands ? { operands: draft.operands } : {}),
+                    }),
                     id,
-                    role: FRAME_ROLE[draft.element],
-                    name: draft.name ?? '',
-                    // The model defaults a band to vertical, and a creation that restated
-                    // the default would be a second place for it to be changed.
-                    ...(draft.orientation === 'horizontal'
-                        ? { orientation: 'horizontal' }
-                        : {}),
-                    // §17.6.4's operator and its operand bands. `alt` is the model's own
-                    // default and is written all the same: unlike an orientation, the
-                    // operator IS the fragment, and a document that left it out would be
-                    // one whose pentagon depends on a default nobody can see.
-                    ...(draft.operator ? { operator: draft.operator } : {}),
-                    ...(draft.operands ? { operands: draft.operands } : {}),
-                    xywh,
                     ...payload(formatId, draft.sourceId),
                 });
                 continue;
             }
-            const kind = draft.kind;
-            const shapeId = mint();
+            // The artefact the toolbar draws, through the ONE assembly the toolbar
+            // and a host with no editor call too (`umlArtefactElements`,
+            // `docs/adr/0045`): the shape, the tiers the kind is worth, the group
+            // last — with the FILE's words in the tiers, never a seed, and this
+            // reader's own names minted in painting order.
+            const [shape, ...rest] = umlArtefactElements(draft.kind, placed, draft.tiers ?? { name: '' }, mint);
+            if (!shape)
+                continue;
             // An interface MARK answers for nothing: §10.4.4 draws it as the notation
             // for a relationship rather than as an element, which is exactly why
             // `model.ts` keeps it out of `artefactOf`. A connector must never resolve
             // to a lollipop.
             if (draft.sourceId && draft.connectable !== false) {
-                shapeOf.set(draft.sourceId, shapeId);
+                shapeOf.set(draft.sourceId, shape.id);
                 boxOf.set(draft.sourceId, placed);
             }
-            elements.push({
-                ...umlNodeProps(kind, { xywh }),
-                id: shapeId,
-                ...payload(formatId, draft.sourceId),
-            });
-            const children = [shapeId];
-            const boxes = umlCompartmentBoxes(kind, placed.x, placed.y, placed.w, placed.h);
-            const tiers = draft.tiers ?? { name: '' };
-            // A mark the notation draws no words on is the SHAPE and nothing else —
-            // and therefore no group either, because a group of one element is a
-            // wrapper a user would have to descend through (`actions.ts`).
-            if (!UML_UNLABELLED_KINDS.has(kind)) {
-                const compartmented = boxes.attributes !== undefined;
-                const tierId = mint();
-                children.push(tierId);
-                elements.push({
-                    ...umlTextProps(compartmented || NAMED_GLYPH_KINDS.has(kind)
-                        ? UML_ROLE.name
-                        : // A lifeline's head is `uml:lifeline-ident`, every other single
-                            // word is `uml:label` — the creation path's own table, read
-                            // rather than restated (`component.ts`).
-                            umlLabelRoleOf(kind), boxes.name, {
-                        fontSize: UML_NAME_FONT_SIZE,
-                        // A note holds a sentence rather than a title (Annex A), and a
-                        // centred paragraph is the one thing on a UML diagram that reads
-                        // as a poem.
-                        align: kind === 'note' ? TextAlign.Left : TextAlign.Center,
-                        // The classifier's name is the heading of a divided box; a
-                        // glyph's one word is not.
-                        ...(compartmented ? { bold: true } : {}),
-                        // The toolbox's own preset: an instance's name is underlined.
-                        decoration: umlNameDecoration(kind),
-                    }),
-                    id: tierId,
-                    text: tiers.name,
-                });
-                for (const [role, box, words] of [
-                    [UML_ROLE.attributes, boxes.attributes, tiers.attributes],
-                    [UML_ROLE.operations, boxes.operations, tiers.operations],
-                ]) {
-                    if (!box)
-                        continue;
-                    const bodyId = mint();
-                    children.push(bodyId);
-                    elements.push({
-                        ...umlTextProps(role, box, {
-                            fontSize: UML_BODY_FONT_SIZE,
-                            align: TextAlign.Left,
-                        }),
-                        id: bodyId,
-                        text: words ?? '',
-                    });
-                }
-            }
-            if (children.length > 1) {
-                // LAST, so it is written after everything it holds — and so the caller's
-                // map already answers for every child by the time this row is created.
-                elements.push({
-                    type: 'group',
-                    id: mint(),
-                    children: Object.fromEntries(children.map(child => [child, true])),
-                });
-            }
+            elements.push({ ...shape, ...payload(formatId, draft.sourceId) }, ...rest);
         }
         // `relations` AND the behaviour edges that live on the Activity and the
         // StateMachine — see {@link umlDrawnEdges} for why there are two places to
@@ -1085,16 +992,10 @@ export function umlElementsFromModel(models, options) {
                 ? undefined
                 : messageAnchors(edge.y + dy, boxOf.get(edge.sourceId), boxOf.get(edge.targetId));
             elements.push({
-                type: 'connector',
+                // The line the edge tool draws (`umlConnectorProps`): STRAIGHT, the
+                // pack's ink, the relationship's own ends.
+                ...umlConnectorProps(edge.kind),
                 id: mint(),
-                role: UML_ROLE[edge.kind],
-                // STRAIGHT, always: UML's lines state a relationship between two
-                // classifiers, and the elbows of an orthogonal router would read as a
-                // route through the diagram that nobody drew (`actions.ts`).
-                mode: ConnectorMode.Straight,
-                stroke: UML_INK,
-                strokeWidth: UML_EDGE_WIDTH,
-                ...UML_EDGE_STYLE[edge.kind],
                 source: { id: source, position: anchors?.source ?? [0.5, 0.5] },
                 target: { id: target, position: anchors?.target ?? [0.5, 0.5] },
                 ...(edge.label ? { text: edge.label } : {}),

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export * from './operators.js';
 export * from './presets.js';
 export * from './reading.js';
 export * from './roles.js';
+export * from './toolbox.js';
 export * from './profiles.js';
 export * from './rules.js';
 export * from './drawio-decode.js';

package/dist/index.js

@@ -37,6 +37,9 @@ export * from './operators.js';
 export * from './presets.js';
 export * from './reading.js';
 export * from './roles.js';
+// The toolbar as pure builders (`docs/adr/0045`), also on `./interchange`:
+// every item that places elements, for a host with no editor.
+export * from './toolbox.js';
 /* ── What a finished diagram is HELD TO: the rule pack and its two levels ─ */
 export * from './profiles.js';
 export * from './rules.js';

package/dist/interchange-headless.d.ts

@@ -11,3 +11,4 @@
  */
 export * from './drawio-decode.js';
 export * from './interchange.js';
+export { UML_TOOLBOX, umlFrameElement, type UmlFrameOptions, umlNodeElements, type UmlNodeTexts, umlRelationElement, } from './toolbox.js';

package/dist/interchange-headless.js

@@ -11,3 +11,6 @@
  */
 export * from './drawio-decode.js';
 export * from './interchange.js';
+// The toolbar as pure builders (`docs/adr/0045`): what a host with no editor
+// places to draw the very elements a user places from the toolbar.
+export { UML_TOOLBOX, umlFrameElement, umlNodeElements, umlRelationElement, } from './toolbox.js';

package/dist/keywords.d.ts

@@ -164,6 +164,32 @@ export declare const UML_OPERATIONS_SEED_KEY = "com.labre.uml.seed.operations";
 export declare const UML_SLOTS_SEED = "attribute = value";
 /** Its own key, resolved at placement like the two above. */
 export declare const UML_SLOTS_SEED_KEY = "com.labre.uml.seed.slots";
+/**
+ * What the SECOND compartment says on a fresh artefact, as `[key, English]`:
+ * the §9.5.4 attribute line every divided box gets, except two.
+ *
+ * Two exceptions and a default, rather than one entry per kind, because the
+ * default is the rule: `+ attribute : Type` is what a divided rectangle's body
+ * tier holds unless the kind's own clause says otherwise.
+ *
+ *  - an **object**'s tier holds SLOTS (§9.8.4) — `attribute = value`, an
+ *    instance giving its classifier's features values rather than redeclaring
+ *    them;
+ *  - a **state**'s holds INTERNAL ACTIVITIES (§14.2.4.4) and is seeded EMPTY.
+ *    That is the one place in this pack where a blank tier is the right
+ *    stencil, and it is the exporter that decides it: `model.ts` reads
+ *    `entry / …`, `do / …` and `exit / …` off these lines and treats a label
+ *    with nothing after it as no behaviour at all, so a seeded `entry / ` would
+ *    be a prompt that reads as content and exports as nothing. §14.2.4's own
+ *    figures draw exactly this — a named state with a ruled-off compartment
+ *    waiting to be filled — and the author types the first line the grammar
+ *    then reads back.
+ *
+ * The state's key is `null` for the reason an unlabelled kind contributes
+ * none: there is no word to translate. The toolbar resolves the key at
+ * placement; a host with no editor takes the English (`toolbox.ts`).
+ */
+export declare function umlBodySeed(kind: UmlNodeKind): readonly [key: string | null, text: string];
 /** What a name compartment states, once its notation has been read off it. */
 export interface UmlStereotypes {
     /**

package/dist/keywords.js

@@ -289,6 +289,38 @@ export const UML_OPERATIONS_SEED_KEY = 'com.labre.uml.seed.operations';
 export const UML_SLOTS_SEED = 'attribute = value';
 /** Its own key, resolved at placement like the two above. */
 export const UML_SLOTS_SEED_KEY = 'com.labre.uml.seed.slots';
+/**
+ * What the SECOND compartment says on a fresh artefact, as `[key, English]`:
+ * the §9.5.4 attribute line every divided box gets, except two.
+ *
+ * Two exceptions and a default, rather than one entry per kind, because the
+ * default is the rule: `+ attribute : Type` is what a divided rectangle's body
+ * tier holds unless the kind's own clause says otherwise.
+ *
+ *  - an **object**'s tier holds SLOTS (§9.8.4) — `attribute = value`, an
+ *    instance giving its classifier's features values rather than redeclaring
+ *    them;
+ *  - a **state**'s holds INTERNAL ACTIVITIES (§14.2.4.4) and is seeded EMPTY.
+ *    That is the one place in this pack where a blank tier is the right
+ *    stencil, and it is the exporter that decides it: `model.ts` reads
+ *    `entry / …`, `do / …` and `exit / …` off these lines and treats a label
+ *    with nothing after it as no behaviour at all, so a seeded `entry / ` would
+ *    be a prompt that reads as content and exports as nothing. §14.2.4's own
+ *    figures draw exactly this — a named state with a ruled-off compartment
+ *    waiting to be filled — and the author types the first line the grammar
+ *    then reads back.
+ *
+ * The state's key is `null` for the reason an unlabelled kind contributes
+ * none: there is no word to translate. The toolbar resolves the key at
+ * placement; a host with no editor takes the English (`toolbox.ts`).
+ */
+export function umlBodySeed(kind) {
+    if (kind === 'object')
+        return [UML_SLOTS_SEED_KEY, UML_SLOTS_SEED];
+    if (kind === 'state')
+        return [null, ''];
+    return [UML_ATTRIBUTES_SEED_KEY, UML_ATTRIBUTES_SEED];
+}
 /**
  * Both spellings of a guillemet pair — the real characters and the ASCII
  * fallback Annex C's note tolerates.

package/dist/presets.d.ts

@@ -1,6 +1,8 @@
-import { TextAlign, TextDecoration } from '@formicoidea/labre-core/model/headless';
+import type { SerializedElementProps } from '@formicoidea/labre-core/interchange';
+import { ConnectorMode, StrokeStyle, TextAlign, TextDecoration } from '@formicoidea/labre-core/model/headless';
 import type { UmlNodeKind } from '@formicoidea/labre-core/model';
-import type { UmlBox } from './component.js';
+import { type UmlBox } from './component.js';
+import { type UmlEdgeRole } from './edge-styles.js';
 /**
  * What a UML shape IS, as props — the ONE description the creation site, the
  * morph and the templates all read (R17).
@@ -166,3 +168,90 @@ export declare function umlTextProps(role: string, box: UmlBox, options: {
  * never carried the field (`node/node-renderer.ts`).
  */
 export declare function umlNameDecoration(kind: UmlNodeKind): TextDecoration | undefined;
+/** The words of an artefact, tier by tier, written exactly as given. */
+export interface UmlTierTexts {
+    name: string;
+    /** The second compartment, one member per line; `''` when absent. */
+    attributes?: string;
+    /** The third compartment, one member per line; `''` when absent. */
+    operations?: string;
+}
+/** The elements of one artefact, as {@link umlArtefactElements} names them. */
+export type UmlArtefactPart = 'shape' | 'name' | 'attributes' | 'operations' | 'group';
+/**
+ * One UML artefact in `box`, as the elements a document holds: the shape, the
+ * tiers its kind is worth, and the group that makes them one thing, LAST.
+ *
+ * The ONE assembly of an artefact (`docs/adr/0045`): the toolbar's actions
+ * (through the toolbox, `toolbox.ts`), a host with no editor (the same
+ * toolbox) and every importer (`umlElementsFromModel`, `import.ts`) write
+ * through here, so a class drawn by hand, one placed by a host and one read
+ * out of a `.puml` file are the same five elements, down to the stroke width.
+ * What differs between them is what they pass: where the box is, the words
+ * (the toolbar's seeds, a host's texts, the file's own), and the ids.
+ *
+ * ## How many tiers is the LAYOUT's answer, not this function's
+ *
+ * A tier is written for each box {@link umlCompartmentBoxes} returns and for
+ * no other: a class gets name, attributes and operations; an object, a
+ * component, an artifact and a state a name over one body tier; a glyph its
+ * one word, placed against its picture. A mark the notation draws no word on
+ * ({@link UML_UNLABELLED_KINDS}) is the SHAPE alone, and therefore no group
+ * either: a group of one element is a wrapper a user would have to descend
+ * through to reach the mark it holds.
+ *
+ * ## The name tier
+ *
+ * `uml:name` on a divided box and on the five {@link NAMED_GLYPH_KINDS};
+ * otherwise the kind's label role ({@link umlLabelRoleOf}: a lifeline's head
+ * is `uml:lifeline-ident`, every other single word `uml:label`). Bold on a
+ * divided box only, where it is the heading; read LEFT on a note, which holds
+ * a sentence rather than a title (Annex A); underlined on an instance
+ * ({@link umlNameDecoration}). A compartment of features is a list of
+ * signatures and is read down its left edge (§9.5.4).
+ *
+ * ## Ids
+ *
+ * `id(part)` is asked once per element, in painting order — shape, name,
+ * attributes, operations, group — and only for the elements written: the
+ * importer mints its `uml-import-<n>` names in that order, the toolbox
+ * prefixes a local name.
+ */
+export declare function umlArtefactElements(kind: UmlNodeKind, box: UmlBox, tiers: UmlTierTexts, id: (part: UmlArtefactPart) => string): SerializedElementProps[];
+/** The five background elements a UML diagram is drawn on and in. */
+export type UmlFrameType = 'umlDiagram' | 'umlSubject' | 'umlPartition' | 'umlRegion' | 'umlFragment';
+/** The box each frame is created at, by the toolbar and the importers. */
+export declare const UML_FRAME_BOX: Readonly<Record<UmlFrameType, {
+    readonly w: number;
+    readonly h: number;
+}>>;
+/**
+ * A frame's props: its type, its role, the fields the caller states (a name, a
+ * diagram's kind, a fragment's operator…) and its box. The toolbox and the
+ * importers both write a frame through here, so the role a frame is born with
+ * is the one table above.
+ */
+export declare function umlFrameProps(type: UmlFrameType, box: {
+    xywh: string;
+}, fields: Record<string, unknown>): SerializedElementProps;
+/**
+ * One UML relationship, as the props `surface.addElement` takes, ends left to
+ * the caller: the role, the STRAIGHT mode, the ink and the line
+ * {@link UML_EDGE_STYLE} says the relationship looks like.
+ *
+ * The edge tools arm the connector with it (`activateUmlEdge`), the toolbox
+ * builds a host's connector from it and the importers draw a file's
+ * relations through it, so the three are one line. STRAIGHT, always: a class
+ * diagram is a graph, not a process laid out in lanes, and the elbows of an
+ * orthogonal router would read as a route through the diagram nobody drew.
+ */
+export declare function umlConnectorProps(edge: UmlEdgeRole): {
+    strokeStyle: StrokeStyle;
+    frontEndpointStyle: import("@formicoidea/labre-core/model").PointStyle;
+    rearEndpointStyle: import("@formicoidea/labre-core/model").PointStyle;
+    type: "connector";
+    role: "uml:association" | "uml:aggregation" | "uml:composition" | "uml:generalization" | "uml:realization" | "uml:dependency" | "uml:anchor" | "uml:include" | "uml:extend" | "uml:deploy" | "uml:manifest" | "uml:communication-path" | "uml:control-flow" | "uml:object-flow" | "uml:transition" | "uml:message-sync" | "uml:message-async" | "uml:message-reply" | "uml:message-create" | "uml:message-delete";
+    mode: ConnectorMode;
+    stroke: string;
+    strokeWidth: number;
+};

package/dist/presets.js

@@ -1,7 +1,10 @@
-import { FontFamily, FontStyle, FontWeight, ShapeStyle, StrokeStyle, TextAlign, TextDecoration, } from '@formicoidea/labre-core/model/headless';
+import { ConnectorMode, FontFamily, FontStyle, FontWeight, ShapeStyle, StrokeStyle, TextAlign, TextDecoration, } from '@formicoidea/labre-core/model/headless';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
-import { UML_CARD, UML_INK, UML_NAME_FONT_SIZE, UML_NODE_BOX, UML_NODE_RADIUS, UML_NODE_STROKE_WIDTH, } from './consts.js';
-import { UML_ROLE_OF_KIND } from './roles.js';
+import { umlCompartmentBoxes, umlLabelRoleOf, } from './component.js';
+import { UML_BODY_FONT_SIZE, UML_CARD, UML_DIAGRAM_BOX, UML_EDGE_WIDTH, UML_FRAGMENT_BOX, UML_INK, UML_NAME_FONT_SIZE, UML_NODE_BOX, UML_NODE_RADIUS, UML_NODE_STROKE_WIDTH, UML_PARTITION_BOX, UML_REGION_BOX, UML_SUBJECT_BOX, } from './consts.js';
+import { UML_EDGE_STYLE } from './edge-styles.js';
+import { UML_UNLABELLED_KINDS } from './keywords.js';
+import { UML_ROLE, UML_ROLE_OF_KIND } from './roles.js';
 /**
  * What a UML shape IS, as props — the ONE description the creation site, the
  * morph and the templates all read (R17).
@@ -320,3 +323,175 @@ export function umlTextProps(role, box, options) {
 export function umlNameDecoration(kind) {
     return kind === 'object' ? TextDecoration.Underline : undefined;
 }
+/* ── The whole artefact: shape, tiers, group ──────────────────────────── */
+/**
+ * The glyph kinds whose one tier is a `uml:name` rather than a `uml:label`.
+ *
+ * The line between the two is drawn by `roles.ts` and it is not about having a
+ * rectangle: `uml:name` is the tier a KEYWORD may be written on and the grammar
+ * reads back, `uml:label` is a name and nothing else. So:
+ *
+ *  - a **package** name is a namespace, parseable and qualified (§12.2.4), and a
+ *    **note**'s text is what the exporter writes as the comment's body;
+ *  - the three **deployment cubes** are named INSIDE their front face, over a
+ *    keyword line — `«device»`, `«executionEnvironment»` (§19.4.4) — which is
+ *    exactly what a name compartment is for. It is also load-bearing rather than
+ *    tidy: the morph's `afterMorph` rewrites `uml:name` and only that, so a cube
+ *    labelled instead of named would morph into a device that never said so.
+ *
+ * Everything else here carries a LABEL: a port's word sits beside a 16-unit
+ * square and the two interface marks' beside a ball and a socket, none of them
+ * inside anything, and none of them ever carrying a keyword.
+ *
+ * Written once, here, since {@link umlArtefactElements} became the one assembly
+ * (`docs/adr/0045`): the toolbar and the importers each used to keep a copy.
+ */
+const NAMED_GLYPH_KINDS = new Set([
+    'package',
+    'note',
+    'node',
+    'device',
+    'execution-environment',
+]);
+/**
+ * One UML artefact in `box`, as the elements a document holds: the shape, the
+ * tiers its kind is worth, and the group that makes them one thing, LAST.
+ *
+ * The ONE assembly of an artefact (`docs/adr/0045`): the toolbar's actions
+ * (through the toolbox, `toolbox.ts`), a host with no editor (the same
+ * toolbox) and every importer (`umlElementsFromModel`, `import.ts`) write
+ * through here, so a class drawn by hand, one placed by a host and one read
+ * out of a `.puml` file are the same five elements, down to the stroke width.
+ * What differs between them is what they pass: where the box is, the words
+ * (the toolbar's seeds, a host's texts, the file's own), and the ids.
+ *
+ * ## How many tiers is the LAYOUT's answer, not this function's
+ *
+ * A tier is written for each box {@link umlCompartmentBoxes} returns and for
+ * no other: a class gets name, attributes and operations; an object, a
+ * component, an artifact and a state a name over one body tier; a glyph its
+ * one word, placed against its picture. A mark the notation draws no word on
+ * ({@link UML_UNLABELLED_KINDS}) is the SHAPE alone, and therefore no group
+ * either: a group of one element is a wrapper a user would have to descend
+ * through to reach the mark it holds.
+ *
+ * ## The name tier
+ *
+ * `uml:name` on a divided box and on the five {@link NAMED_GLYPH_KINDS};
+ * otherwise the kind's label role ({@link umlLabelRoleOf}: a lifeline's head
+ * is `uml:lifeline-ident`, every other single word `uml:label`). Bold on a
+ * divided box only, where it is the heading; read LEFT on a note, which holds
+ * a sentence rather than a title (Annex A); underlined on an instance
+ * ({@link umlNameDecoration}). A compartment of features is a list of
+ * signatures and is read down its left edge (§9.5.4).
+ *
+ * ## Ids
+ *
+ * `id(part)` is asked once per element, in painting order — shape, name,
+ * attributes, operations, group — and only for the elements written: the
+ * importer mints its `uml-import-<n>` names in that order, the toolbox
+ * prefixes a local name.
+ */
+export function umlArtefactElements(kind, box, tiers, id) {
+    const shape = {
+        // NO `text`: the words are the tiers below, and the shape is a body and
+        // nothing else (R16).
+        ...umlNodeProps(kind, {
+            xywh: new Bound(box.x, box.y, box.w, box.h).serialize(),
+        }),
+        id: id('shape'),
+    };
+    if (UML_UNLABELLED_KINDS.has(kind))
+        return [shape];
+    const boxes = umlCompartmentBoxes(kind, box.x, box.y, box.w, box.h);
+    const compartmented = boxes.attributes !== undefined;
+    const members = [
+        shape,
+        {
+            ...umlTextProps(compartmented || NAMED_GLYPH_KINDS.has(kind)
+                ? UML_ROLE.name
+                : umlLabelRoleOf(kind), boxes.name, {
+                fontSize: UML_NAME_FONT_SIZE,
+                align: kind === 'note' ? TextAlign.Left : TextAlign.Center,
+                ...(compartmented ? { bold: true } : {}),
+                decoration: umlNameDecoration(kind),
+            }),
+            id: id('name'),
+            text: tiers.name,
+        },
+    ];
+    for (const [part, role, tierBox] of [
+        ['attributes', UML_ROLE.attributes, boxes.attributes],
+        ['operations', UML_ROLE.operations, boxes.operations],
+    ]) {
+        if (!tierBox)
+            continue;
+        members.push({
+            ...umlTextProps(role, tierBox, {
+                fontSize: UML_BODY_FONT_SIZE,
+                align: TextAlign.Left,
+            }),
+            id: id(part),
+            text: tiers[part] ?? '',
+        });
+    }
+    return [
+        ...members,
+        {
+            type: 'group',
+            id: id('group'),
+            // A plain record is a legal `children`: the group's own `propsToY` takes
+            // the KEYS. No title, deliberately: the group renderer paints one only
+            // while the artefact is selected, and a package announcing itself as
+            // "Group 3" above its own name is a label nobody wrote.
+            children: Object.fromEntries(members.map(m => [m.id, true])),
+        },
+    ];
+}
+/** The box each frame is created at, by the toolbar and the importers. */
+export const UML_FRAME_BOX = {
+    umlDiagram: UML_DIAGRAM_BOX,
+    umlSubject: UML_SUBJECT_BOX,
+    umlPartition: UML_PARTITION_BOX,
+    umlRegion: UML_REGION_BOX,
+    umlFragment: UML_FRAGMENT_BOX,
+};
+/** The role each frame carries — one table, read by every creation site. */
+const UML_FRAME_ROLE = {
+    umlDiagram: UML_ROLE.diagram,
+    umlSubject: UML_ROLE.subject,
+    umlPartition: UML_ROLE.partition,
+    umlRegion: UML_ROLE.region,
+    umlFragment: UML_ROLE.fragment,
+};
+/**
+ * A frame's props: its type, its role, the fields the caller states (a name, a
+ * diagram's kind, a fragment's operator…) and its box. The toolbox and the
+ * importers both write a frame through here, so the role a frame is born with
+ * is the one table above.
+ */
+export function umlFrameProps(type, box, fields) {
+    return { type, role: UML_FRAME_ROLE[type], ...fields, xywh: box.xywh };
+}
+/* ── The relationships ────────────────────────────────────────────────── */
+/**
+ * One UML relationship, as the props `surface.addElement` takes, ends left to
+ * the caller: the role, the STRAIGHT mode, the ink and the line
+ * {@link UML_EDGE_STYLE} says the relationship looks like.
+ *
+ * The edge tools arm the connector with it (`activateUmlEdge`), the toolbox
+ * builds a host's connector from it and the importers draw a file's
+ * relations through it, so the three are one line. STRAIGHT, always: a class
+ * diagram is a graph, not a process laid out in lanes, and the elbows of an
+ * orthogonal router would read as a route through the diagram nobody drew.
+ */
+export function umlConnectorProps(edge) {
+    return {
+        type: 'connector',
+        role: UML_ROLE[edge],
+        mode: ConnectorMode.Straight,
+        stroke: UML_INK,
+        strokeWidth: UML_EDGE_WIDTH,
+        ...UML_EDGE_STYLE[edge],
+    };
+}