@formicoidea/labre-framework-uml 0.42.0

package/dist/commands.js

@@ -0,0 +1,983 @@
+import { activateUmlEdge, createUmlClassifier, createUmlDiagram, createUmlFragment, createUmlInteractionUse, createUmlNode, createUmlPartition, createUmlRegion, createUmlSubject, exportUmlPlantumlFile, exportUmlXmiFile, importUmlDrawioFile, importUmlPlantumlFile, importUmlXmiFile, umlDiagramsForExport, } from './actions.js';
+import { umlLegendEntry, UML_LEGEND_BOX } from './legend.js';
+import { umlExportPlantumlIcon, umlExportXmiIcon, umlImportDrawioIcon, umlImportPlantumlIcon, umlImportXmiIcon, umlToolbarIcon, UML_TOOLBOX_ICONS, } from './toolbar/icons.js';
+const SPECS = [
+    /* ── The cold row, authored in the order it paints ─────────────────── */
+    // The first nineteen entries are authored in SUB-MENU order rather than
+    // in catalogue order, and since the PO ruling of 2026-09-16 the two
+    // readings no longer coincide. One `order` still feeds both surfaces, but
+    // the catalogue GROUPS by `category` — a section gathers its rows wherever
+    // they sit in this list — while the row does not group at all. So the
+    // thirteen a cold start paints come first, in the order they paint, and
+    // the six entries that decline the row but belong to one of their three
+    // sections are slotted in where that section needs them: `addObject`
+    // before the class relations, `addNote` before the general ones, and the
+    // four below the last seat.
+    //
+    // Both readings are pinned in `commands-manifest.unit.spec.ts` — the
+    // nominated fourteen, the rendered thirteen, and the nine sections.
+    {
+        id: 'addDiagram',
+        label: 'UML diagram',
+        iconKey: 'uml.diagram',
+        kind: 'artefact',
+        category: 'general',
+        element: 'board',
+        board: true,
+        senior: true,
+        // Wrapped, not passed by reference: `run` is called `(std, invocation)` and
+        // `createUmlDiagram` takes `(std, kind = 'class')`, so handing it over bare
+        // would make the invocation object the diagram's KIND. The frame is always
+        // born a class diagram; the picker on its own row is what changes it.
+        run: std => createUmlDiagram(std),
+    },
+    {
+        id: 'addClass',
+        label: 'Class',
+        iconKey: 'uml.class',
+        kind: 'artefact',
+        category: 'class-diagram',
+        element: 'node:class',
+        senior: true,
+        run: std => createUmlClassifier(std, 'class'),
+    },
+    {
+        id: 'addInterface',
+        label: 'Interface',
+        iconKey: 'uml.interface',
+        kind: 'artefact',
+        category: 'class-diagram',
+        element: 'node:interface',
+        senior: true,
+        run: std => createUmlClassifier(std, 'interface'),
+    },
+    {
+        id: 'addEnumeration',
+        label: 'Enumeration',
+        iconKey: 'uml.enumeration',
+        kind: 'artefact',
+        category: 'class-diagram',
+        element: 'node:enumeration',
+        senior: true,
+        run: std => createUmlClassifier(std, 'enumeration'),
+    },
+    {
+        id: 'addPackage',
+        label: 'Package',
+        iconKey: 'uml.package',
+        kind: 'artefact',
+        category: 'general',
+        element: 'node:package',
+        senior: true,
+        run: std => createUmlNode(std, 'package'),
+    },
+    {
+        id: 'addActor',
+        label: 'Actor',
+        iconKey: 'uml.actor',
+        kind: 'artefact',
+        category: 'use-case-diagram',
+        element: 'node:actor',
+        senior: true,
+        run: std => createUmlNode(std, 'actor'),
+    },
+    {
+        id: 'addUseCase',
+        label: 'Use case',
+        iconKey: 'uml.use-case',
+        kind: 'artefact',
+        category: 'use-case-diagram',
+        element: 'node:use-case',
+        senior: true,
+        run: std => createUmlNode(std, 'use-case'),
+    },
+    {
+        id: 'addSubject',
+        label: 'Subject',
+        iconKey: 'uml.subject',
+        kind: 'artefact',
+        category: 'use-case-diagram',
+        element: 'boundary:subject',
+        senior: true,
+        run: createUmlSubject,
+    },
+    {
+        // An instance diagram is a SECOND reading of a class diagram — you draw one
+        // once the classes exist — so it is the first thing to leave the row.
+        id: 'addObject',
+        label: 'Object',
+        iconKey: 'uml.object',
+        kind: 'artefact',
+        category: 'class-diagram',
+        element: 'node:object',
+        senior: false,
+        run: std => createUmlClassifier(std, 'object'),
+    },
+    {
+        id: 'associationTool',
+        label: 'Association',
+        iconKey: 'uml.association',
+        kind: 'tool',
+        category: 'class-diagram',
+        element: 'connector:association',
+        senior: true,
+        run: std => activateUmlEdge(std, 'association'),
+    },
+    {
+        id: 'addNote',
+        label: 'Note',
+        iconKey: 'uml.note',
+        kind: 'artefact',
+        category: 'general',
+        element: 'node:note',
+        senior: false,
+        // ponytail: DEMOTED from the nominated fourteen to make room for
+        // `uml.importXmi` (tranche G, `docs/adr/0019`). The budget is fourteen plus
+        // the single over-nomination the PO authorized on 2026-08-28, which BPMN
+        // has spent, so a fifteenth UML nomination would break
+        // `registry.unit.spec.ts` — and an import is the one entry a user wants on
+        // an EMPTY board, which is exactly when the sub-menu is open (the same
+        // ruling that put `bpmn.importXml` in its row). The note is still one click
+        // away behind "More artefacts…".
+        //
+        // Which of the fourteen an import ought to displace is a PO curation point
+        // with usage data behind it, not a tranche's to settle: the note was picked
+        // because it is the only nominated artefact that annotates a diagram rather
+        // than being part of one. Revisit with the phase-2 recette.
+        run: std => createUmlNode(std, 'note'),
+    },
+    {
+        id: 'generalizationTool',
+        label: 'Generalization',
+        iconKey: 'uml.generalization',
+        kind: 'tool',
+        category: 'general',
+        element: 'connector:generalization',
+        senior: true,
+        run: std => activateUmlEdge(std, 'generalization'),
+    },
+    {
+        id: 'dependencyTool',
+        label: 'Dependency',
+        iconKey: 'uml.dependency',
+        kind: 'tool',
+        category: 'general',
+        element: 'connector:dependency',
+        senior: true,
+        run: std => activateUmlEdge(std, 'dependency'),
+    },
+    {
+        id: 'includeTool',
+        label: 'Include',
+        iconKey: 'uml.include',
+        kind: 'tool',
+        category: 'use-case-diagram',
+        element: 'connector:include',
+        senior: true,
+        run: std => activateUmlEdge(std, 'include'),
+    },
+    {
+        id: 'extendTool',
+        label: 'Extend',
+        iconKey: 'uml.extend',
+        kind: 'tool',
+        category: 'use-case-diagram',
+        element: 'connector:extend',
+        senior: true,
+        run: std => activateUmlEdge(std, 'extend'),
+    },
+    /* ── Past the thirteenth seat, still in the three sections above ────── */
+    {
+        id: 'aggregationTool',
+        label: 'Aggregation',
+        iconKey: 'uml.aggregation',
+        kind: 'tool',
+        category: 'class-diagram',
+        element: 'connector:aggregation',
+        senior: false,
+        run: std => activateUmlEdge(std, 'aggregation'),
+    },
+    {
+        id: 'compositionTool',
+        label: 'Composition',
+        iconKey: 'uml.composition',
+        kind: 'tool',
+        category: 'class-diagram',
+        element: 'connector:composition',
+        senior: false,
+        run: std => activateUmlEdge(std, 'composition'),
+    },
+    {
+        id: 'realizationTool',
+        label: 'Realization',
+        iconKey: 'uml.realization',
+        kind: 'tool',
+        category: 'general',
+        element: 'connector:realization',
+        senior: false,
+        run: std => activateUmlEdge(std, 'realization'),
+    },
+    {
+        id: 'anchorTool',
+        label: 'Anchor',
+        iconKey: 'uml.anchor',
+        kind: 'tool',
+        category: 'general',
+        element: 'connector:anchor',
+        senior: false,
+        run: std => activateUmlEdge(std, 'anchor'),
+    },
+    /* ── Component diagram (§11.6.4, §11.3.4, §10.4.4) ──────────────────── */
+    // Nothing from here down contests the row, and it is ONE decision rather
+    // than fifty: the thirteen a user meets on a cold start are the class and
+    // use-case diagrams an architect draws first, and no later tranche gets to
+    // re-argue that from inside itself. Which is why the sections below can be
+    // authored the way the catalogue reads them — by DIAGRAM KIND, in the order
+    // of the frame's own kind picker (`kinds.ts`) — with nothing to interleave.
+    {
+        id: 'addComponent',
+        label: 'Component',
+        iconKey: 'uml.component',
+        kind: 'artefact',
+        category: 'component-diagram',
+        element: 'node:component',
+        senior: false,
+        run: std => createUmlClassifier(std, 'component'),
+    },
+    {
+        id: 'addPort',
+        label: 'Port',
+        iconKey: 'uml.port',
+        kind: 'artefact',
+        category: 'component-diagram',
+        element: 'node:port',
+        senior: false,
+        run: std => createUmlNode(std, 'port'),
+    },
+    {
+        id: 'addProvidedInterface',
+        label: 'Provided interface',
+        iconKey: 'uml.provided-interface',
+        kind: 'artefact',
+        category: 'component-diagram',
+        element: 'node:provided-interface',
+        senior: false,
+        run: std => createUmlNode(std, 'provided-interface'),
+    },
+    {
+        id: 'addRequiredInterface',
+        label: 'Required interface',
+        iconKey: 'uml.required-interface',
+        kind: 'artefact',
+        category: 'component-diagram',
+        element: 'node:required-interface',
+        senior: false,
+        run: std => createUmlNode(std, 'required-interface'),
+    },
+    /* ── Deployment diagram (§19.2.4, §19.3.4, §19.4.4) ─────────────────── */
+    {
+        id: 'addArtifact',
+        label: 'Artifact',
+        iconKey: 'uml.artifact',
+        kind: 'artefact',
+        category: 'deployment-diagram',
+        element: 'node:artifact',
+        senior: false,
+        run: std => createUmlClassifier(std, 'artifact'),
+    },
+    {
+        id: 'addNode',
+        label: 'Node',
+        iconKey: 'uml.node',
+        kind: 'artefact',
+        category: 'deployment-diagram',
+        element: 'node:node',
+        senior: false,
+        run: std => createUmlNode(std, 'node'),
+    },
+    {
+        id: 'addDevice',
+        label: 'Device',
+        iconKey: 'uml.device',
+        kind: 'artefact',
+        category: 'deployment-diagram',
+        element: 'node:device',
+        senior: false,
+        run: std => createUmlNode(std, 'device'),
+    },
+    {
+        id: 'addExecutionEnvironment',
+        label: 'Execution environment',
+        iconKey: 'uml.execution-environment',
+        kind: 'artefact',
+        category: 'deployment-diagram',
+        element: 'node:execution-environment',
+        senior: false,
+        run: std => createUmlNode(std, 'execution-environment'),
+    },
+    {
+        id: 'deployTool',
+        label: 'Deploy',
+        iconKey: 'uml.deploy',
+        kind: 'tool',
+        category: 'deployment-diagram',
+        element: 'connector:deploy',
+        senior: false,
+        run: std => activateUmlEdge(std, 'deploy'),
+    },
+    {
+        id: 'manifestTool',
+        label: 'Manifest',
+        iconKey: 'uml.manifest',
+        kind: 'tool',
+        category: 'deployment-diagram',
+        element: 'connector:manifest',
+        senior: false,
+        run: std => activateUmlEdge(std, 'manifest'),
+    },
+    {
+        id: 'communicationPathTool',
+        label: 'Communication path',
+        iconKey: 'uml.communication-path',
+        kind: 'tool',
+        category: 'deployment-diagram',
+        element: 'connector:communication-path',
+        senior: false,
+        run: std => activateUmlEdge(std, 'communication-path'),
+    },
+    /* ── Activity diagram (§15.2.4, §15.3.4, §15.4.4, §16.3.4, §16.10.4) ── */
+    {
+        id: 'addAction',
+        label: 'Action',
+        iconKey: 'uml.action',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:action',
+        senior: false,
+        run: std => createUmlNode(std, 'action'),
+    },
+    {
+        id: 'addInitial',
+        label: 'Initial node',
+        iconKey: 'uml.initial',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:initial',
+        senior: false,
+        run: std => createUmlNode(std, 'initial'),
+    },
+    {
+        id: 'addActivityFinal',
+        label: 'Activity final',
+        iconKey: 'uml.activity-final',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:activity-final',
+        senior: false,
+        run: std => createUmlNode(std, 'activity-final'),
+    },
+    {
+        id: 'addFlowFinal',
+        label: 'Flow final',
+        iconKey: 'uml.flow-final',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:flow-final',
+        senior: false,
+        run: std => createUmlNode(std, 'flow-final'),
+    },
+    {
+        id: 'addDecision',
+        label: 'Decision',
+        iconKey: 'uml.decision',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:decision',
+        senior: false,
+        run: std => createUmlNode(std, 'decision'),
+    },
+    {
+        id: 'addFork',
+        label: 'Fork',
+        iconKey: 'uml.fork',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:fork',
+        senior: false,
+        run: std => createUmlNode(std, 'fork'),
+    },
+    {
+        id: 'addObjectNode',
+        label: 'Object node',
+        iconKey: 'uml.object-node',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:object-node',
+        senior: false,
+        run: std => createUmlNode(std, 'object-node'),
+    },
+    {
+        id: 'addSendSignal',
+        label: 'Send signal',
+        iconKey: 'uml.send-signal',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:send-signal',
+        senior: false,
+        run: std => createUmlNode(std, 'send-signal'),
+    },
+    {
+        id: 'addAcceptEvent',
+        label: 'Accept event',
+        iconKey: 'uml.accept-event',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:accept-event',
+        senior: false,
+        run: std => createUmlNode(std, 'accept-event'),
+    },
+    {
+        id: 'addTimeEvent',
+        label: 'Time event',
+        iconKey: 'uml.time-event',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'node:time-event',
+        senior: false,
+        run: std => createUmlNode(std, 'time-event'),
+    },
+    {
+        // A swimlane is a BOUNDARY, which is why it sits after the activity's
+        // elements and before its two flows: it is neither an element of the model
+        // nor the sheet the model is drawn on, it is a band drawn ROUND part of the
+        // drawing, and what belongs to it is read back from where things sit
+        // (§15.6.4). Its kind is what files it; its type is what places it inside
+        // that section.
+        id: 'addPartition',
+        label: 'Partition',
+        iconKey: 'uml.partition',
+        kind: 'artefact',
+        category: 'activity-diagram',
+        element: 'boundary:partition',
+        senior: false,
+        run: createUmlPartition,
+    },
+    {
+        id: 'controlFlowTool',
+        label: 'Control flow',
+        iconKey: 'uml.control-flow',
+        kind: 'tool',
+        category: 'activity-diagram',
+        element: 'connector:control-flow',
+        senior: false,
+        run: std => activateUmlEdge(std, 'control-flow'),
+    },
+    {
+        id: 'objectFlowTool',
+        label: 'Object flow',
+        iconKey: 'uml.object-flow',
+        kind: 'tool',
+        category: 'activity-diagram',
+        element: 'connector:object-flow',
+        senior: false,
+        run: std => activateUmlEdge(std, 'object-flow'),
+    },
+    /* ── State machine diagram (§14.2.4) ────────────────────────────────── */
+    {
+        id: 'addState',
+        label: 'State',
+        iconKey: 'uml.state',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:state',
+        senior: false,
+        // The one behaviour artefact that walks the CLASSIFIER path: §14.2.4 draws
+        // a state as a divided box, so it arrives with a name compartment and the
+        // internal-activities tier the renderer rules off (`actions.ts`).
+        run: std => createUmlClassifier(std, 'state'),
+    },
+    {
+        id: 'addFinalState',
+        label: 'Final state',
+        iconKey: 'uml.final-state',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:final-state',
+        senior: false,
+        run: std => createUmlNode(std, 'final-state'),
+    },
+    {
+        id: 'addChoice',
+        label: 'Choice',
+        iconKey: 'uml.choice',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:choice',
+        senior: false,
+        run: std => createUmlNode(std, 'choice'),
+    },
+    {
+        id: 'addJunction',
+        label: 'Junction',
+        iconKey: 'uml.junction',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:junction',
+        senior: false,
+        run: std => createUmlNode(std, 'junction'),
+    },
+    {
+        id: 'addShallowHistory',
+        label: 'Shallow history',
+        iconKey: 'uml.shallow-history',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:shallow-history',
+        senior: false,
+        run: std => createUmlNode(std, 'shallow-history'),
+    },
+    {
+        id: 'addDeepHistory',
+        label: 'Deep history',
+        iconKey: 'uml.deep-history',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:deep-history',
+        senior: false,
+        run: std => createUmlNode(std, 'deep-history'),
+    },
+    {
+        id: 'addEntryPoint',
+        label: 'Entry point',
+        iconKey: 'uml.entry-point',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:entry-point',
+        senior: false,
+        run: std => createUmlNode(std, 'entry-point'),
+    },
+    {
+        id: 'addExitPoint',
+        label: 'Exit point',
+        iconKey: 'uml.exit-point',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:exit-point',
+        senior: false,
+        run: std => createUmlNode(std, 'exit-point'),
+    },
+    {
+        id: 'addTerminate',
+        label: 'Terminate',
+        iconKey: 'uml.terminate',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'node:terminate',
+        senior: false,
+        run: std => createUmlNode(std, 'terminate'),
+    },
+    {
+        // A composite state, as the container it is drawn as (§14.2.4) — and a
+        // BOUNDARY for the same reason the partition is one: what is IN a region is
+        // read back from geometry, never from a list. So it closes its kind's
+        // elements, just before the transition tool.
+        id: 'addRegion',
+        label: 'Region',
+        iconKey: 'uml.region',
+        kind: 'artefact',
+        category: 'state-machine-diagram',
+        element: 'boundary:region',
+        senior: false,
+        run: createUmlRegion,
+    },
+    {
+        id: 'transitionTool',
+        label: 'Transition',
+        iconKey: 'uml.transition',
+        kind: 'tool',
+        category: 'state-machine-diagram',
+        element: 'connector:transition',
+        senior: false,
+        run: std => activateUmlEdge(std, 'transition'),
+    },
+    /* ── Sequence diagram (§17.2.4, §17.4.4, §17.6.4, §17.7.4) ──────────── */
+    {
+        id: 'addLifeline',
+        label: 'Lifeline',
+        iconKey: 'uml.lifeline',
+        kind: 'artefact',
+        category: 'sequence-diagram',
+        element: 'node:lifeline',
+        senior: false,
+        run: std => createUmlNode(std, 'lifeline'),
+    },
+    {
+        id: 'addExecution',
+        label: 'Execution',
+        iconKey: 'uml.execution',
+        kind: 'artefact',
+        category: 'sequence-diagram',
+        element: 'node:execution',
+        senior: false,
+        run: std => createUmlNode(std, 'execution'),
+    },
+    {
+        id: 'addDestruction',
+        label: 'Destruction',
+        iconKey: 'uml.destruction',
+        kind: 'artefact',
+        category: 'sequence-diagram',
+        element: 'node:destruction',
+        senior: false,
+        run: std => createUmlNode(std, 'destruction'),
+    },
+    {
+        // A combined fragment is a BOUNDARY for the reason the partition and the
+        // region are: it is neither an element of the model nor the sheet the model
+        // is drawn on, it is a box drawn ROUND part of the drawing, and what is
+        // inside it is read back from where things sit (§17.6.4). So it and the
+        // interaction use close the sequence diagram's elements, before its five
+        // message tools.
+        id: 'addFragment',
+        label: 'Combined fragment',
+        iconKey: 'uml.fragment',
+        kind: 'artefact',
+        category: 'sequence-diagram',
+        element: 'boundary:fragment',
+        senior: false,
+        // Wrapped rather than passed by reference, the same call `uml.addDiagram`
+        // makes: `run` is called `(std, invocation)` and `createUmlFragment` takes
+        // `(std, operator = 'alt')`, so handing it over bare would make the
+        // invocation object the fragment's OPERATOR.
+        run: std => createUmlFragment(std),
+    },
+    {
+        // The same element with `ref` in its tag (§17.7.4) — a command of its own
+        // because it is a different modelling act: pointing at another diagram
+        // rather than branching this one. See `createUmlInteractionUse`.
+        id: 'addInteractionUse',
+        label: 'Interaction use',
+        iconKey: 'uml.interaction-use',
+        kind: 'artefact',
+        category: 'sequence-diagram',
+        element: 'boundary:interaction-use',
+        senior: false,
+        run: createUmlInteractionUse,
+    },
+    {
+        id: 'messageSyncTool',
+        label: 'Synchronous message',
+        iconKey: 'uml.message-sync',
+        kind: 'tool',
+        category: 'sequence-diagram',
+        element: 'connector:message-sync',
+        senior: false,
+        run: std => activateUmlEdge(std, 'message-sync'),
+    },
+    {
+        id: 'messageAsyncTool',
+        label: 'Asynchronous message',
+        iconKey: 'uml.message-async',
+        kind: 'tool',
+        category: 'sequence-diagram',
+        element: 'connector:message-async',
+        senior: false,
+        run: std => activateUmlEdge(std, 'message-async'),
+    },
+    {
+        id: 'messageReplyTool',
+        label: 'Reply message',
+        iconKey: 'uml.message-reply',
+        kind: 'tool',
+        category: 'sequence-diagram',
+        element: 'connector:message-reply',
+        senior: false,
+        run: std => activateUmlEdge(std, 'message-reply'),
+    },
+    {
+        id: 'messageCreateTool',
+        label: 'Create message',
+        iconKey: 'uml.message-create',
+        kind: 'tool',
+        category: 'sequence-diagram',
+        element: 'connector:message-create',
+        senior: false,
+        run: std => activateUmlEdge(std, 'message-create'),
+    },
+    {
+        id: 'messageDeleteTool',
+        label: 'Delete message',
+        iconKey: 'uml.message-delete',
+        kind: 'tool',
+        category: 'sequence-diagram',
+        element: 'connector:message-delete',
+        senior: false,
+        run: std => activateUmlEdge(std, 'message-delete'),
+    },
+];
+/**
+ * The authored slot the first INTERCHANGE command sits in — straight after the
+ * last artefact, with no gap anywhere before it.
+ *
+ * A named constant rather than five literals because six declarations three
+ * hundred lines apart have to agree about it: the toolbox's own `order`, and
+ * the two exports and three imports that follow it. The header says why the
+ * whole block is last.
+ */
+const UML_INTERCHANGE_ORDER = SPECS.length;
+/**
+ * `{ legend }` when the entry owes a row, `{}` when it does not — the frame and
+ * the interaction use are the two that do not. See `legend.ts`.
+ */
+function legendOf(spec) {
+    const entry = umlLegendEntry(spec.element);
+    return entry ? { legend: entry } : {};
+}
+const toolboxCommands = SPECS.map((spec, index) => ({
+    id: `uml.${spec.id}`,
+    owner: 'uml',
+    kind: spec.kind,
+    labelKey: `com.labre.commands.uml.${spec.id}`,
+    labelFallback: spec.label,
+    category: spec.category,
+    iconKey: spec.iconKey,
+    surfaces: spec.senior
+        ? ['senior-menu', 'catalogue', 'palette', 'agent']
+        : ['catalogue', 'palette', 'agent'],
+    // Authored order, with no gap in it: the artefacts run 0…SPECS.length-1 and
+    // the interchange block starts at {@link UML_INTERCHANGE_ORDER}. The gap that
+    // used to reserve slot 1 for the XMI import is gone with the reason for it.
+    order: index,
+    scope: 'edgeless',
+    // Keyless by intent, and at sixty-nine commands there is no chord alphabet
+    // that would not be arbitrary — still bindable from Settings › Shortcuts,
+    // which is what `toShortcutDescriptor` being total buys.
+    defaultKeys: { mac: [], other: [] },
+    availability: 'always',
+    run: spec.run,
+    telemetry: { framework: 'uml', element: spec.element, board: spec.board },
+    // The legend row this entry's artefact puts on the frame it is drawn on —
+    // derived from the very `element` value above, so the sixty-two rows of the
+    // old table are sixty-two commands that cannot fall out of step with it. The
+    // frame declares the BOX instead of a row: a legend must not list the paper.
+    ...(spec.board ? { legendBox: UML_LEGEND_BOX } : legendOf(spec)),
+}));
+/**
+ * The two EXPORTS — the commands whose subject is a whole DIAGRAM.
+ *
+ * ## Two formats, two commands, and neither implies the other
+ *
+ * ADR 0012 declares interchange per framework × format × direction, so PlantUML
+ * and XMI are two rows rather than one row with an option. They are also two
+ * different promises: XMI 2.5.1 is the OMG's own interchange format and carries
+ * the model (classifiers, their attributes and operations, the typed ends of
+ * every relationship); PlantUML carries the same model as a source a human
+ * reads and a renderer redraws. Both are `tier: 'semantic'` — neither is a
+ * picture — and `interchange.ts` is where that is declared.
+ *
+ * ## Why the selection is the scope
+ *
+ * A UML diagram frame is ONE diagram — a class diagram, a use-case diagram —
+ * and the point of drawing three side by side is that they are three diagrams.
+ * Merging them would produce a document neither format can express (a `@startuml`
+ * has one title; an XMI `uml:Model` one root), so the selection decides: one
+ * frame, one document; several frames, several documents in one file.
+ *
+ * ## Surfaces
+ *
+ * Both decline `'senior-menu'`: the sub-menu is what you reach for to DRAW
+ * something, and an export draws nothing — and UML is already past the cap, so
+ * a slot spent here is a slot taken from an artefact. They keep `'catalogue'`,
+ * which is not a category claim but the registry's own invariant: the catalogue
+ * is the TOTAL surface.
+ *
+ * ## The section they are filed under
+ *
+ * `interchange`, which is where BPMN and Wardley already file theirs and which
+ * is therefore the section a host that translated the header once has already
+ * translated. It is also the one section {@link Spec.category} did NOT re-file
+ * by diagram kind on 2026-09-16, and could not have: an XMI file is not a kind
+ * of diagram, it is what a diagram of any kind is written to.
+ *
+ * UML shipped them under `diagrams` — the section its FRAME was filed under —
+ * and the consequence was the one the PO's recette of 2026-09-14 reported:
+ * `groupCommandsByCategory` orders sections by the order their category is
+ * first MET, so five interchange commands sat inside the first section of the
+ * catalogue, above every artefact the framework draws. Their own section,
+ * authored last, puts them where the other two frameworks put theirs.
+ *
+ * On the frame's own row they sit in the "⋮" rather than as buttons, and in the
+ * ALWAYS-ON toolbar module — the entry hides itself when the command is absent
+ * from the registry (the `when` guard every `commandAction` carries), so with
+ * the UML tooling flag off the row is the resize toggle alone and nothing on it
+ * can be clicked into a no-op. See `toolbar/config.ts`.
+ */
+const exportCommands = [
+    {
+        id: 'uml.exportPlantuml',
+        owner: 'uml',
+        kind: 'action',
+        labelKey: 'com.labre.commands.uml.exportPlantuml',
+        labelFallback: 'Export as PlantUML',
+        descriptionKey: 'com.labre.commands.uml.exportPlantuml.description',
+        descriptionFallback: 'Download the selected diagram as PlantUML source, ready to paste into any PlantUML renderer.',
+        category: 'interchange',
+        iconKey: 'uml.export-plantuml',
+        surfaces: ['catalogue', 'contextual-toolbar', 'palette', 'agent'],
+        // First of the interchange block, which is first of the EXPORTS: the PO's
+        // reading of 2026-09-14 puts what leaves the board before what arrives on
+        // an empty one.
+        order: UML_INTERCHANGE_ORDER,
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+        availability: 'selection',
+        run: exportUmlPlantumlFile,
+        telemetry: { framework: 'uml', element: 'board:export-plantuml' },
+        // A diagram in the selection, and no more than that: an export READS, so
+        // it is offered on a read-only document — which is precisely the diagram
+        // somebody wants to take away.
+        when: std => umlDiagramsForExport(std).length > 0,
+    },
+    {
+        id: 'uml.exportXmi',
+        owner: 'uml',
+        kind: 'action',
+        labelKey: 'com.labre.commands.uml.exportXmi',
+        labelFallback: 'Export as XMI',
+        descriptionKey: 'com.labre.commands.uml.exportXmi.description',
+        descriptionFallback: 'Download the selected diagram as XMI 2.5.1, the OMG interchange format every UML tool reads.',
+        category: 'interchange',
+        iconKey: 'uml.export-xmi',
+        surfaces: ['catalogue', 'contextual-toolbar', 'palette', 'agent'],
+        order: UML_INTERCHANGE_ORDER + 1,
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+        availability: 'selection',
+        run: exportUmlXmiFile,
+        telemetry: { framework: 'uml', element: 'board:export-xmi' },
+        when: std => umlDiagramsForExport(std).length > 0,
+    },
+];
+/**
+ * The three IMPORTS — where a UML board comes FROM (`docs/adr/0019`).
+ *
+ * ## Three rows, because the unit of declaration is the triple
+ *
+ * ADR 0012 declares interchange per framework × format × direction, so three
+ * formats are three commands and never one command with a format picker. They
+ * are also three different PROMISES, and the promise is made by each command's
+ * own label and description before the picker opens (P2): PlantUML and XMI
+ * carry a MODEL and take the whole preservation contract; draw.io carries a
+ * DRAWING, and every UML fact read out of it is a guess made from a style
+ * string. A picker with three entries behind one button would hide exactly that
+ * difference at exactly the moment it matters.
+ *
+ * ## One nomination, and it cost the note its seat
+ *
+ * R5 puts an import in the senior sub-menu — the same ruling of 2026-08-28 that
+ * nominated `bpmn.importXml`: a board comes from a file, and the sub-menu is
+ * the first thing a user opens on an empty canvas. The budget is
+ * `SENIOR_MENU_CAP` nominations plus the single over-nomination the PO
+ * authorized that day, which BPMN has spent — so UML's fifteenth nomination
+ * would break `registry.unit.spec.ts` rather than merely crowd the row.
+ *
+ * So exactly ONE of the three takes the seat, and it is XMI: it is the OMG's
+ * own interchange format, it is the one every modelling tool writes, and it is
+ * the one that re-imports what this pack exports. The other two sit one click
+ * away in the catalogue behind "More artefacts…". `uml.addNote` is the entry
+ * that stood down for it, with the reasoning recorded at its declaration — a
+ * PO curation point, flagged there rather than settled here.
+ *
+ * The seat is a nomination and not a cold-start button: authored last, it is
+ * the fourteenth of fourteen nominations and the row renders thirteen, so it
+ * appears the first time the user reaches for it (ADR 0014 § R3) and not
+ * before. The header states the arbitration that put it there.
+ */
+const importCommands = [
+    {
+        id: 'uml.importXmi',
+        owner: 'uml',
+        kind: 'action',
+        labelKey: 'com.labre.commands.uml.importXmi',
+        labelFallback: 'Import XMI',
+        descriptionKey: 'com.labre.commands.uml.importXmi.description',
+        descriptionFallback: 'Open an XMI 2.5.1 model as a diagram. What Labre cannot draw is kept in the document, and the import says what it was.',
+        category: 'interchange',
+        iconKey: 'uml.import-xmi',
+        // The one nominated import — see the header. Not the contextual toolbar: a
+        // contextual toolbar is a statement about a SELECTION, and the moment this
+        // is most wanted is on a board with nothing on it.
+        surfaces: ['senior-menu', 'catalogue', 'palette', 'agent'],
+        // Authored LAST among the nominations, which is what makes it the one of
+        // the fourteen an overflowed row's thirteen slots leave out until somebody
+        // uses it (ADR 0014 § R3). The alternative — the second slot it held from
+        // tranche G until the PO's recette of 2026-09-14 — buys the cold row at the
+        // price of the catalogue, because one `order` serves both surfaces. See the
+        // header.
+        order: UML_INTERCHANGE_ORDER + 2,
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+        // An import WRITES, so a read-only document is one it cannot run on and the
+        // declaration says so. `'always'` would light the entry on a read-only
+        // board, do nothing when clicked, and put the same untruth into the
+        // serializable manifest a host reads. Nothing has to be SELECTED — which is
+        // the mirror image of the exports beside it — so there is no `when`.
+        availability: 'editable',
+        run: importUmlXmiFile,
+        // `board:` and not `diagram:`: an export names the frame whose toolbar
+        // launched it, and an import is launched with no frame anywhere.
+        telemetry: { framework: 'uml', element: 'board:import-xmi' },
+    },
+    {
+        id: 'uml.importPlantuml',
+        owner: 'uml',
+        kind: 'action',
+        labelKey: 'com.labre.commands.uml.importPlantuml',
+        labelFallback: 'Import PlantUML',
+        descriptionKey: 'com.labre.commands.uml.importPlantuml.description',
+        descriptionFallback: 'Open a PlantUML source as a diagram. Lines Labre cannot read are kept in the document, and the import says which.',
+        category: 'interchange',
+        iconKey: 'uml.import-plantuml',
+        surfaces: ['catalogue', 'palette', 'agent'],
+        order: UML_INTERCHANGE_ORDER + 3,
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+        availability: 'editable',
+        run: importUmlPlantumlFile,
+        telemetry: { framework: 'uml', element: 'board:import-plantuml' },
+    },
+    {
+        id: 'uml.importDrawio',
+        owner: 'uml',
+        kind: 'action',
+        labelKey: 'com.labre.commands.uml.importDrawio',
+        labelFallback: 'Import draw.io drawing',
+        descriptionKey: 'com.labre.commands.uml.importDrawio.description',
+        descriptionFallback: 'Recognise a draw.io drawing as UML, best effort: the shapes and arrows it understands become a diagram, and it says what it could not read.',
+        category: 'interchange',
+        iconKey: 'uml.import-drawio',
+        surfaces: ['catalogue', 'palette', 'agent'],
+        order: UML_INTERCHANGE_ORDER + 4,
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+        availability: 'editable',
+        run: importUmlDrawioFile,
+        telemetry: { framework: 'uml', element: 'board:import-drawio' },
+    },
+];
+export const umlCommands = [
+    ...toolboxCommands,
+    ...exportCommands,
+    ...importCommands,
+];
+export const umlCommandIcons = {
+    ...UML_TOOLBOX_ICONS,
+    // The senior BUTTON's glyph, registered so `FrameworkDescriptor.iconKey`
+    // resolves through `getCommandIcon` (rule R1). No command names it.
+    'uml.toolbar': umlToolbarIcon,
+    'uml.export-plantuml': umlExportPlantumlIcon,
+    'uml.export-xmi': umlExportXmiIcon,
+    'uml.import-plantuml': umlImportPlantumlIcon,
+    'uml.import-xmi': umlImportXmiIcon,
+    'uml.import-drawio': umlImportDrawioIcon,
+};