@formicoidea/labre-framework-wardley 0.40.0 → 0.42.0

package/dist/actions.js

@@ -1,17 +1,18 @@
-import { backgroundSize, DefaultTool, indexOverBackgrounds, runInterchangeImportFile, } from '@formicoidea/labre-core/blocks/surface';
+import { backgroundSize, containingFrame, DefaultTool, indexOverBackgrounds, runInterchangeImportFile, } from '@formicoidea/labre-core/blocks/surface';
 import { ConnectorTool } from '@formicoidea/labre-core/gfx/connector';
 import { createGroupCommand } from '@formicoidea/labre-core/gfx/group';
-import { ConnectorMode, FontWeight, FrameworkBackgroundElementModel, PointStyle, StrokeStyle, WardleyBackgroundElementModel, } from '@formicoidea/labre-core/model';
+import { PolygonTool } from '@formicoidea/labre-core/gfx/shape';
+import { ConnectorMode, FontWeight, FrameworkBackgroundElementModel, TextElementModel, WardleyBackgroundElementModel, } from '@formicoidea/labre-core/model';
 import { NotificationProvider, translateKey, } from '@formicoidea/labre-core/shared/services';
 import { downloadBlob } from '@formicoidea/labre-core/shared/utils';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
-import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
+import { GfxControllerIdentifier, } from '@formicoidea/labre-core/std/gfx';
 import { WARDLEY_BACKGROUND } from './background.js';
 import { WARDLEY_SVG_IMPORT } from './interchange.js';
 import { wardleyBoardFrom, wardleySafeFilename, } from './export.js';
 import { WARDLEY_OWM_EXPORT, WARDLEY_OWM_IMPORT } from './interchange.js';
-import { HANDLE_SIZE, INERTIA_SIZE, LABEL_GAP, LINK_GREY, LINK_STROKE_WIDTH, PORTER_DEFAULT_LETTER, WARDLEY_RED, } from './node/consts.js';
-import { wardleyAreaBox, wardleyAreaProps, wardleyCanonicalBox, wardleyHandleBox, wardleyHandleProps, wardleyInertiaProps, WARDLEY_LABEL_H, WARDLEY_LABEL_W, wardleyLabelProps, wardleyMarketDotBoxes, wardleyMarketDotProps, wardleyMarketLinkPairs, wardleyMarketLinkProps, WARDLEY_NODE_LABEL, WARDLEY_NODE_SIZE, wardleyNodeProps, wardleyPorterArrowProps, wardleyPorterArrows, wardleyPorterLetterProps, } from './presets.js';
+import { INERTIA_SIZE, PORTER_DEFAULT_LETTER } from './node/consts.js';
+import { wardleyAreaBox, wardleyAreaProps, wardleyCanonicalBox, WARDLEY_EDGE_STYLE, wardleyHandleBox, wardleyHandleProps, wardleyInertiaProps, wardleyLabelBoxFor, wardleyLabelProps, wardleyMarketDotBoxes, wardleyMarketDotProps, wardleyMarketLinkPairs, wardleyMarketLinkProps, WARDLEY_NODE_LABEL, wardleyNodeLabelKey, wardleyNodeProps, wardleyPorterArrowProps, wardleyPorterArrows, wardleyPorterLetterProps, } from './presets.js';
 import { WARDLEY_ROLE } from './roles.js';
 /**
  * Standalone creation/activation actions for the Wardley toolbox — the
@@ -24,48 +25,62 @@ import { WARDLEY_ROLE } from './roles.js';
  * segment/module discrimination it carried is now `CommandInvocation.surface`.
  */
 /**
- * Per-variant default label overrides applied at creation (all remain editable
- * afterwards via the inline editor / toggles). The gradient itself is driven by
- * `variant` in the renderer.
- *
- * TODO(PF2 follow-up): these write ENGLISH PROSE into the document. Since PF2
- * the ten label props default to `undefined` precisely so the declaration's
- * i18n keys are reachable — but a map created as `opportunity` or `benefit`
- * lands with "Opportunity" / "Benefit" / "Investment" already persisted as if
- * the user had typed them, so those three are un-localisable for the life of
- * the document. Only `classic` and `evolution-gradient` are fully localisable
- * today.
- *
- * The fix is to make the variant part of the declaration — one axis/end-label
- * set per variant, each naming its own `labelKey` — rather than a bag of prop
- * overrides applied at creation. Out of scope here (it changes what a variant
- * IS). This is now the ONLY copy: the four background templates are derived
- * from these four commands, so the table goes away in one place.
+ * The three axis words a translated variant's background is seeded with —
+ * declared once, so the resolver below and the manifest
+ * (`../translations.ts`) read the very same fallback.
  */
-const BACKGROUND_VARIANT_DEFAULTS = {
-    classic: {},
-    // The Y axis becomes "Opportunity"; phase labels keep the classic defaults.
+export const WARDLEY_AXIS_SEED = {
     opportunity: {
-        yAxisTitle: 'Opportunity',
-        showVisibilityLabels: false,
-        showCornerLabels: false,
+        key: 'com.labre.wardley.seed.axis-opportunity',
+        fallback: 'Opportunity',
     },
-    // The Y axis splits into Benefit (top) / Investment (bottom) around a zero
-    // line drawn by the renderer.
     benefit: {
-        yAxisTitle: '',
-        visibilityHigh: 'Benefit',
-        visibilityLow: 'Investment',
-        showCornerLabels: false,
+        key: 'com.labre.wardley.seed.axis-benefit',
+        fallback: 'Benefit',
+    },
+    investment: {
+        key: 'com.labre.wardley.seed.axis-investment',
+        fallback: 'Investment',
     },
-    // Keeps the classic labels (Value Chain / Uncharted / Industrialized…); only
-    // the grey gradient differs.
-    'evolution-gradient': {},
 };
-// The label box, now owned by `presets.ts` — the local names stay so the four
-// placements below keep reading as they did.
-const LABEL_H = WARDLEY_LABEL_H;
-const LABEL_W = WARDLEY_LABEL_W;
+/**
+ * Per-variant default label overrides applied at creation (all remain editable
+ * afterwards via the inline editor / toggles). The gradient itself is driven by
+ * `variant` in the renderer.
+ *
+ * Resolved through the translation seam since the i18n pass (#278): the ten
+ * label props still default to `undefined` on the declaration itself, but
+ * `opportunity` and `benefit` are the two variants whose Y axis is PROSE the
+ * gesture bakes into the document at creation — `WARDLEY_AXIS_SEED` above is
+ * what a host's catalogue is offered for the three words, resolved HERE, once,
+ * exactly like every other seed in this file. `classic` and
+ * `evolution-gradient` keep the classic labels (Value Chain / Uncharted /
+ * Industrialized…), which are declaration `labelKey`s and were already fully
+ * localisable — this function names no override for them.
+ */
+function backgroundVariantDefaults(gfx) {
+    const axis = (def) => translateKey(gfx.std, def.key, def.fallback);
+    return {
+        classic: {},
+        // The Y axis becomes "Opportunity"; phase labels keep the classic defaults.
+        opportunity: {
+            yAxisTitle: axis(WARDLEY_AXIS_SEED.opportunity),
+            showVisibilityLabels: false,
+            showCornerLabels: false,
+        },
+        // The Y axis splits into Benefit (top) / Investment (bottom) around a zero
+        // line drawn by the renderer.
+        benefit: {
+            yAxisTitle: '',
+            visibilityHigh: axis(WARDLEY_AXIS_SEED.benefit),
+            visibilityLow: axis(WARDLEY_AXIS_SEED.investment),
+            showCornerLabels: false,
+        },
+        // Keeps the classic labels (Value Chain / Uncharted / Industrialized…); only
+        // the grey gradient differs.
+        'evolution-gradient': {},
+    };
+}
 function finish(gfx, id) {
     gfx.doc.captureSync();
     gfx.tool.setTool(DefaultTool);
@@ -128,7 +143,7 @@ export function createWardleyBackground(gfx, variant = 'classic') {
         // declaration decides, and the toolbar toggle takes over from there.
         resizeEnabled: WARDLEY_BACKGROUND.geometry.resizable,
         variant,
-        ...BACKGROUND_VARIANT_DEFAULTS[variant],
+        ...backgroundVariantDefaults(gfx)[variant],
         xywh: new Bound(centerX - width / 2, centerY - height / 2, width, height).serialize(),
     });
     finish(gfx, id);
@@ -142,10 +157,15 @@ export function createWardleyNode(gfx, kind) {
     const surface = gfx.surface;
     if (!surface)
         return;
-    const { w } = WARDLEY_NODE_SIZE[kind];
     const { centerX: cx, centerY: cy } = gfx.viewport;
     const nodeId = addNode(surface, kind, cx, cy);
-    const labelId = addLabel(surface, WARDLEY_NODE_LABEL[kind], cx + w / 2 + LABEL_GAP, cy - LABEL_H / 2);
+    const { x, y, textAlign } = wardleyLabelBoxFor(kind, cx, cy);
+    const labelId = addLabel(surface, 
+    // Resolved HERE, once — the prompt a node nobody has named still carries,
+    // exactly like a BPMN node's caption. `gfx.std` is how this file reaches
+    // the translation seam: these creation sites take `GfxController`, not
+    // `BlockStdScope`, directly (`WardleyView` reads the same member).
+    translateKey(gfx.std, wardleyNodeLabelKey(kind), WARDLEY_NODE_LABEL[kind]), x, y, textAlign);
     finish(gfx, group(gfx, [nodeId, labelId]));
 }
 /** Create an inertia bar (filled black rect). */
@@ -170,15 +190,14 @@ export function createWardleyPipeline(gfx) {
     if (!gfx.surface)
         return;
     const { centerX: cx, centerY: cy } = gfx.viewport;
-    const d = HANDLE_SIZE;
-    const top = cy - WARDLEY_NODE_SIZE.pipeline.h / 2;
     // Body: a WardleyNode rect, made non-connectable by `kind: 'pipeline'`.
     const bodyId = addNode(gfx.surface, 'pipeline', cx, cy);
     // Handle: a node-sized WardleyNode square straddling the top edge. Inherits
     // `centerAnchorOnly` so connectors attach to its center only.
     const handleId = gfx.surface.addElement(wardleyHandleProps({ xywh: wardleyHandleBox(cx, cy) }));
     // Label centered horizontally on the pipeline, sitting ABOVE the handle.
-    const labelId = addLabel(gfx.surface, WARDLEY_NODE_LABEL.pipeline, cx - 60, top - d / 2 - LABEL_H - LABEL_GAP, 'center');
+    const { x, y, textAlign } = wardleyLabelBoxFor('pipeline', cx, cy);
+    const labelId = addLabel(gfx.surface, translateKey(gfx.std, wardleyNodeLabelKey('pipeline'), WARDLEY_NODE_LABEL.pipeline), x, y, textAlign);
     // Nested groups: (handle + label), then (body + that group).
     const innerId = group(gfx, [handleId, labelId]);
     finish(gfx, group(gfx, [bodyId, innerId]));
@@ -195,14 +214,14 @@ export function createWardleyMarket(gfx) {
     if (!surface)
         return;
     const { centerX: cx, centerY: cy } = gfx.viewport;
-    const R = WARDLEY_NODE_SIZE.market.w / 2;
     // Outer circle = the market node (connectable, center-only).
     const circleId = addNode(surface, 'market', cx, cy);
     // 3 inner component nodes (thick border, no label) at the triangle vertices.
     const dotIds = wardleyMarketDotBoxes(cx, cy).map(xywh => surface.addElement(wardleyMarketDotProps({ xywh })));
     // Triangle: 3 attached connectors (auto-route center-to-center, clipped).
     const connIds = wardleyMarketLinkPairs(dotIds).map(([a, b]) => surface.addElement(wardleyMarketLinkProps(a, b)));
-    const labelId = addLabel(surface, WARDLEY_NODE_LABEL.market, cx + R + LABEL_GAP, cy - LABEL_H / 2);
+    const { x, y, textAlign } = wardleyLabelBoxFor('market', cx, cy);
+    const labelId = addLabel(surface, translateKey(gfx.std, wardleyNodeLabelKey('market'), WARDLEY_NODE_LABEL.market), x, y, textAlign);
     finish(gfx, group(gfx, [circleId, ...dotIds, ...connIds, labelId]));
 }
 /**
@@ -259,14 +278,12 @@ export function createWardleyAccelerator(gfx, kind) {
     const surface = gfx.surface;
     if (!surface)
         return;
-    const { w } = WARDLEY_NODE_SIZE[kind];
     const { centerX: cx, centerY: cy } = gfx.viewport;
     const nodeId = addNode(surface, kind, cx, cy);
-    const rightwards = kind === 'accelerator';
-    const labelId = addLabel(surface, WARDLEY_NODE_LABEL[kind], 
-    // A label box is a fixed LABEL_W wide whatever it reads, so a right-aligned
-    // one has to start a box-width before the edge the words must end on.
-    rightwards ? cx + w / 2 + LABEL_GAP : cx - w / 2 - LABEL_GAP - LABEL_W, cy - LABEL_H / 2, rightwards ? 'left' : 'right', FontWeight.SemiBold);
+    // Which side, and which alignment, are the placement's answer: the
+    // decelerator's mirrored label is one of the two rules `presets.ts` states.
+    const { x, y, textAlign } = wardleyLabelBoxFor(kind, cx, cy);
+    const labelId = addLabel(surface, translateKey(gfx.std, wardleyNodeLabelKey(kind), WARDLEY_NODE_LABEL[kind]), x, y, textAlign, FontWeight.SemiBold);
     finish(gfx, group(gfx, [nodeId, labelId]));
 }
 /**
@@ -298,6 +315,40 @@ export function createWardleyArea(gfx, shape) {
     lowerWardleyArea(gfx, id);
     finish(gfx, id);
 }
+/**
+ * Arm the interactive polygon tool to draw a ZONE, corner by corner.
+ *
+ * The polygonal half of the kind is a TOOL and the rectangular half an artefact,
+ * and the asymmetry is the gesture rather than an inconsistency: a rectangle has
+ * one shape whatever its size, so placing one and dragging its handles is the
+ * whole of drawing it — while a polygon IS its corners, and a prefabricated
+ * pentagon parked in the middle of the map is never the outline anybody wanted
+ * (PO decision of 2026-09-16). The author clicks each corner and closes on the
+ * first one; Escape cancels and fewer than three corners draws nothing, both of
+ * which the tool already decides.
+ *
+ * What comes back is a Wardley area and not a plain polygon, because the tool
+ * creates the element from the props handed here — same fill, rim, role and
+ * inner-text settings as {@link createWardleyArea} writes, from the same
+ * description — and then lowers it the way that function does.
+ */
+export function activateWardleyAreaPolygon(gfx) {
+    const { centerX: cx, centerY: cy } = gfx.viewport;
+    gfx.tool.setTool(PolygonTool, {
+        // The box and the default pentagon in here are a placeholder: the tool
+        // spreads this bag before the outline the author drew, so both are
+        // overwritten. They are still stated rather than stripped, because what a
+        // zone IS has exactly one description (`presets.ts`) and taking two keys
+        // out of it here would be a second one.
+        props: wardleyAreaProps('polygon', {
+            xywh: wardleyAreaBox('polygon', cx, cy),
+        }),
+        // A zone is lowered the moment it exists, for the reason
+        // {@link createWardleyArea} gives at length: drawn last it would paint over
+        // every component it groups and intercept their clicks.
+        onCreated: lowerWardleyArea,
+    });
+}
 /**
  * Send one already-placed area to the depth it belongs at — see
  * {@link createWardleyArea} for why a zone is lowered at all.
@@ -368,22 +419,10 @@ export function activateWardleyConnector(gfx, kind) {
         // fall on a dependency.
         role: kind === 'link' ? WARDLEY_ROLE.dependency : WARDLEY_ROLE.changeArrow,
         // The look rides on the activation, never through the last-props store:
-        // the plain connector tool must keep the user's own style (#144 M1).
-        style: kind === 'arrow'
-            ? {
-                stroke: WARDLEY_RED,
-                strokeStyle: StrokeStyle.Dash,
-                strokeWidth: LINK_STROKE_WIDTH,
-                frontEndpointStyle: PointStyle.None,
-                rearEndpointStyle: PointStyle.Triangle,
-            }
-            : {
-                stroke: LINK_GREY,
-                strokeStyle: StrokeStyle.Solid,
-                strokeWidth: LINK_STROKE_WIDTH,
-                frontEndpointStyle: PointStyle.None,
-                rearEndpointStyle: PointStyle.None,
-            },
+        // the plain connector tool must keep the user's own style (#144 M1). The
+        // style itself is {@link WARDLEY_EDGE_STYLE}, so the legend row this tool
+        // subscribes pictures the very line the tool draws.
+        style: { ...WARDLEY_EDGE_STYLE[kind] },
     });
     // The wardley palette stays open (native sub-menu behaviour): it only
     // closes on re-click of the senior button, another senior tool, or Escape.
@@ -400,33 +439,74 @@ export function activateWardleyConnector(gfx, kind) {
  */
 const EXPORT_WARNINGS_KEY = 'com.labre.commands.wardley.exportOwm.warnings';
 const EXPORT_WARNINGS_FALLBACK = 'What this export could not write down';
-/** The maps on the surface — what the export command is offered against. */
-export function wardleyMapsOnBoard(std) {
-    const surface = std.get(GfxControllerIdentifier).surface;
-    return (surface?.elementModels ?? []).filter((model) => model instanceof WardleyBackgroundElementModel);
+/**
+ * The Wardley maps in the SELECTION — what the export is offered against.
+ *
+ * No read-only filter, for `c4BoardsForExport`'s reason: an export writes
+ * nothing, and a map published read-only is precisely the one somebody wants to
+ * take away.
+ */
+export function wardleyMapsSelected(std) {
+    return std
+        .get(GfxControllerIdentifier)
+        .selection.selectedElements.filter((model) => model instanceof WardleyBackgroundElementModel);
 }
 /**
- * Everything on the surface the exporter speaks about, in document order.
+ * The elements the export speaks about, in DOCUMENT order: the selected map(s)
+ * and what they wholly contain.
  *
- * The half that needs an editor, and only that half: reading the surface. The
- * picking is {@link wardleyBoardFrom}, which the interchange capability calls
- * with the same elements and no `std` at all (`docs/adr/0012`, P3).
+ * Membership is `containingFrame` on the map's element bound — whole
+ * containment, ties to the smaller id — which is the one answer the validation
+ * engine and the legend already give (PF2.4). The candidates are EVERY map on
+ * the surface and not just the selected ones, so an artefact inside two
+ * overlapping maps is attributed here exactly as the engine attributes it.
+ */
+export function wardleyExportElementsOf(std) {
+    const elements = std.get(GfxControllerIdentifier).surface?.elementModels ?? [];
+    const allMaps = elements.filter((model) => model instanceof WardleyBackgroundElementModel);
+    const selected = new Set(wardleyMapsSelected(std));
+    return elements.filter(element => {
+        if (element instanceof WardleyBackgroundElementModel) {
+            return selected.has(element);
+        }
+        // ponytail: a label is the NAME of a node, not an artefact of its own, so it
+        // crosses UNSCOPED. `matchLabels` (export.ts) only binds one within
+        // LABEL_MATCH_TOLERANCE of a kept node and drops the rest, while a long name
+        // beside a node near the right edge legitimately hangs over the map bound —
+        // scoping labels by containment would export that node unnamed.
+        if (element instanceof TextElementModel &&
+            element.role === WARDLEY_ROLE.label) {
+            return true;
+        }
+        const map = containingFrame(element.elementBound, allMaps, candidate => candidate.elementBound);
+        return map !== null && selected.has(map);
+    });
+}
+/**
+ * What the exporter speaks about, as a picked board.
+ *
+ * The half that needs an editor, and only that half: reading the surface and
+ * scoping it to the selection. The picking is {@link wardleyBoardFrom}, which
+ * the interchange capability calls with the same elements and no `std` at all
+ * (`docs/adr/0012`, P3).
  */
 export function wardleyBoardOf(std) {
-    return wardleyBoardFrom(std.get(GfxControllerIdentifier).surface?.elementModels ?? []);
+    return wardleyBoardFrom(wardleyExportElementsOf(std));
 }
 /**
- * Serialize the board as an OWM document and hand it to the browser.
+ * Serialize the selected map as an OWM document and hand it to the browser.
  *
  * Three steps, and only the first and the last know what an editor is: read the
- * surface, run the DECLARED capability, download what it produced. The middle
- * step is not re-implemented here — the document, the filename and the content
- * type all come out of `WARDLEY_OWM_EXPORT.run`, so the command and the
- * registry cannot describe the same map differently. There is one door, and the
- * registry is the label on it.
+ * selected map's perimeter, run the DECLARED capability, download what it
+ * produced. The middle step is not re-implemented here — the document, the
+ * filename and the content type all come out of `WARDLEY_OWM_EXPORT.run`, so
+ * the command and the registry cannot describe the same map differently.
+ *
+ * Selecting SEVERAL maps still produces one file: an OWM document is one map,
+ * and `exportWardleyOwmWithWarnings` says so out loud in its warnings.
  */
 export function exportOwmFile(std) {
-    const elements = std.get(GfxControllerIdentifier).surface?.elementModels ?? [];
+    const elements = wardleyExportElementsOf(std);
     const title = std.store.workspace.meta.getDocMeta(std.store.id)?.title;
     const { text, filename, mime, warnings } = WARDLEY_OWM_EXPORT.run(elements, {
         name: wardleySafeFilename(title),

package/dist/commands.js

@@ -1,7 +1,8 @@
 import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
-import { activateWardleyConnector, createWardleyAccelerator, createWardleyArea, createWardleyBackground, createWardleyInertia, createWardleyMarket, createWardleyNode, createWardleyPipeline, createWardleyPorter, exportOwmFile, importOwmFile, importWardleySvgFile, wardleyMapsOnBoard, } from './actions.js';
+import { activateWardleyAreaPolygon, activateWardleyConnector, createWardleyAccelerator, createWardleyArea, createWardleyBackground, createWardleyInertia, createWardleyMarket, createWardleyNode, createWardleyPipeline, createWardleyPorter, exportOwmFile, importOwmFile, importWardleySvgFile, wardleyMapsSelected, } from './actions.js';
+import { WARDLEY_LEGEND_BOX, wardleyLegendEntry, } from './legend.js';
 import { WARDLEY_ROLE, WARDLEY_ROLES } from './roles.js';
-import { wardleyAcceleratorIcon, wardleyAnchorIcon, wardleyAreaPolygonIcon, wardleyAreaRectIcon, wardleyArrowIcon, wardleyBackgroundIcon, wardleyDeceleratorIcon, wardleyBenefitIcon, wardleyComponentIcon, wardleyEcosystemIcon, wardleyEvolutionGradientIcon, wardleyExportOwmIcon, wardleyImportOwmIcon, wardleyImportSvgIcon, wardleyInertiaIcon, wardleyLinkIcon, wardleyMarketIcon, wardleyMethodIcon, wardleyOpportunityIcon, wardleyPipelineIcon, wardleyPorterIcon, } from './toolbar/icons.js';
+import { wardleyAcceleratorIcon, wardleyAnchorIcon, wardleyAreaPolygonIcon, wardleyAreaRectIcon, wardleyArrowIcon, wardleyBackgroundIcon, wardleyDeceleratorIcon, wardleyBenefitIcon, wardleyComponentIcon, wardleyEcosystemIcon, wardleyEvolutionGradientIcon, wardleyExportOwmIcon, wardleyImportOwmIcon, wardleyImportSvgIcon, wardleyInertiaIcon, wardleyLinkIcon, wardleyMarketIcon, wardleyMethodIcon, wardleyOpportunityIcon, wardleyPipelineIcon, wardleyPorterIcon, wardleyToolbarIcon, } from './toolbar/icons.js';
 const SPECS = [
     {
         id: 'addBackground',
@@ -47,6 +48,7 @@ const SPECS = [
     },
     {
         id: 'addComponent',
+        legendRole: WARDLEY_ROLE.component,
         label: 'Component',
         labelKey: 'com.labre.keyboardShortcuts.wardley.addComponent',
         key: 'c',
@@ -58,6 +60,7 @@ const SPECS = [
     },
     {
         id: 'addMethod',
+        legendRole: WARDLEY_ROLE.method,
         label: 'Component + method',
         labelKey: 'com.labre.keyboardShortcuts.wardley.addMethod',
         key: 'm',
@@ -69,6 +72,7 @@ const SPECS = [
     },
     {
         id: 'addMarket',
+        legendRole: WARDLEY_ROLE.market,
         label: 'Market',
         iconKey: 'wardley.market',
         category: 'nodes',
@@ -78,6 +82,7 @@ const SPECS = [
     },
     {
         id: 'addEcosystem',
+        legendRole: WARDLEY_ROLE.ecosystem,
         label: 'Ecosystem',
         iconKey: 'wardley.ecosystem',
         category: 'nodes',
@@ -87,6 +92,7 @@ const SPECS = [
     },
     {
         id: 'addAnchor',
+        legendRole: WARDLEY_ROLE.anchor,
         label: 'Anchor',
         key: 'a',
         iconKey: 'wardley.anchor',
@@ -97,6 +103,7 @@ const SPECS = [
     },
     {
         id: 'addPipeline',
+        legendRole: WARDLEY_ROLE.pipeline,
         label: 'Pipeline',
         labelKey: 'com.labre.keyboardShortcuts.wardley.addPipeline',
         key: 'p',
@@ -108,6 +115,7 @@ const SPECS = [
     },
     {
         id: 'linkTool',
+        legendRole: WARDLEY_ROLE.dependency,
         label: 'Link',
         labelKey: 'com.labre.keyboardShortcuts.wardley.linkTool',
         key: 'l',
@@ -120,6 +128,7 @@ const SPECS = [
     },
     {
         id: 'evolutionArrow',
+        legendRole: WARDLEY_ROLE.changeArrow,
         label: 'Arrow (evolution)',
         labelKey: 'com.labre.keyboardShortcuts.wardley.evolutionArrow',
         key: 'e',
@@ -132,6 +141,7 @@ const SPECS = [
     },
     {
         id: 'addInertia',
+        legendRole: WARDLEY_ROLE.inertia,
         label: 'Inertia',
         labelKey: 'com.labre.keyboardShortcuts.wardley.addInertia',
         key: 'i',
@@ -148,6 +158,7 @@ const SPECS = [
     // a framework binds past that by host override rather than by default.
     {
         id: 'addPorter',
+        legendRole: WARDLEY_ROLE.porter,
         label: "Porter's forces",
         iconKey: 'wardley.porter',
         category: 'nodes',
@@ -162,6 +173,7 @@ const SPECS = [
     // past that by host override.
     {
         id: 'addAccelerator',
+        legendRole: WARDLEY_ROLE.accelerator,
         label: 'Accelerator',
         iconKey: 'wardley.accelerator',
         category: 'nodes',
@@ -171,6 +183,7 @@ const SPECS = [
     },
     {
         id: 'addDecelerator',
+        legendRole: WARDLEY_ROLE.decelerator,
         label: 'Decelerator',
         iconKey: 'wardley.decelerator',
         category: 'nodes',
@@ -182,12 +195,14 @@ const SPECS = [
     // around a chain that already exists, so it is the last gesture of a map and
     // reads as the last entry of the row. Two entries and ONE kind — the shape is
     // the choice, and offering it as two buttons is what saves the author a trip
-    // through "switch type" for the commonest case.
+    // through "switch type" for the commonest case. One kind, but two GESTURES:
+    // the rectangle is placed, the polygon is drawn corner by corner.
     //
     // Keyless, like the porter and the two climate arrows: the `w` chord seats
     // eight artefacts and a framework binds past that by host override.
     {
         id: 'addAreaRect',
+        legendRole: WARDLEY_ROLE.area,
         label: 'Area (rectangle)',
         iconKey: 'wardley.area-rect',
         category: 'areas',
@@ -197,12 +212,20 @@ const SPECS = [
     },
     {
         id: 'addAreaPolygon',
+        legendRole: WARDLEY_ROLE.area,
         label: 'Area (polygon)',
         iconKey: 'wardley.area-polygon',
         category: 'areas',
-        kind: 'artefact',
+        // A TOOL, and the only entry of this row that is one: a polygon IS its
+        // corners, so the author draws them rather than receiving a pentagon to
+        // reshape (PO decision of 2026-09-16, #343). `element` is untouched — the
+        // artefact this gesture produces is the same one — and the change of kind
+        // is what moves its event from `FrameworkElementAdded` to
+        // `FrameworkToolPicked`, which is the truth about a tool: it is picked, and
+        // the drawing may still be abandoned with Escape.
+        kind: 'tool',
         element: 'node:area-polygon',
-        run: gfx => createWardleyArea(gfx, 'polygon'),
+        run: activateWardleyAreaPolygon,
     },
 ];
 /**
@@ -239,6 +262,13 @@ const toolboxCommands = SPECS.map((spec, order) => ({
     availability: 'always',
     run: std => spec.run(std.get(GfxControllerIdentifier)),
     telemetry: { framework: 'wardley', element: spec.element, board: spec.board },
+    // The legend, SUBSCRIBED rather than tabulated (`docs/adr/0009`'s sibling):
+    // the command that draws the artefact names the row that pictures it, and
+    // the sheet's own command carries the box the rows are drawn in. Which
+    // sub-title a row files under is `category`, so the sections are the very
+    // groups the catalogue already shows.
+    ...(spec.legendRole ? { legend: wardleyLegendEntry(spec.legendRole) } : {}),
+    ...(spec.id === 'addBackground' ? { legendBox: WARDLEY_LEGEND_BOX } : {}),
 }));
 /**
  * The IMPORT — the first Wardley command whose subject is a whole map rather
@@ -290,30 +320,18 @@ const importCommand = {
 /**
  * The EXPORT — the other direction of the same format.
  *
- * It declines `'senior-menu'`, and the asymmetry with the import above is the
- * ruling BPMN already carries: the sub-menu is where a board COMES FROM, and an
- * export is what you do to a board you already have. It keeps `'catalogue'`,
- * which is the registry's own invariant rather than a category claim — a
- * command missing from the catalogue is unreachable the moment its framework
- * overflows the fourteen slots — plus the palette and the agent. No
- * `'contextual-toolbar'` either, and that is a declaration rather than an
- * oversight: a contextual-toolbar surface is rendered by an element's own
- * `ToolbarModuleConfig`, and declaring one nothing invokes would put an entry
- * in the manifest that no toolbar draws.
+ * It mirrors `bpmn.exportXml` and `c4.exportMermaid` (R5 of
+ * `docs/add-a-framework/02-framework-rules.md`): an import is where a board
+ * comes FROM, so it sits in the sub-menu; an export is what you do to a board
+ * you already have, so it sits in the selected map's "⋮" (`toolbar/config.ts`).
  *
- * `'always'` with a `when` on the BOARD, and the pair is deliberate. An export
- * READS: it needs no selection, and it is offered on a locked map and on a
- * read-only document — which is precisely the board somebody wants to take
- * away. What it DOES need is a plot to measure coordinates against, and that is
- * a fact about the surface rather than about the selection: a Wardley node has
- * no `visibility` prop, so its position on the plot IS its coordinate, and with
- * no map there is nothing to invert. `'selection'` would be BPMN's shape copied
- * for the look of it — that command's precondition genuinely is a selected
- * pool, and this one's is not.
+ * An export READS, so `availability: 'selection'` with a `when` on the selected
+ * MAP is the whole precondition: it is offered on a locked map and on a
+ * read-only document — precisely the map somebody wants to take away.
  *
- * **v1 writes one map.** An OWM document is one map; a board holding several is
- * written against the first in document order and the export says so out loud
- * in its warnings.
+ * **Scope: the selected map's perimeter.** The file holds that map and what it
+ * wholly contains ({@link wardleyExportElementsOf}). Selecting several maps
+ * still writes one map, and the export says so out loud in its warnings.
  */
 const exportCommand = {
     id: 'wardley.exportOwm',
@@ -322,17 +340,17 @@ const exportCommand = {
     labelKey: 'com.labre.commands.wardley.exportOwm',
     labelFallback: 'Export Wardley map (OWM)',
     descriptionKey: 'com.labre.commands.wardley.exportOwm.description',
-    descriptionFallback: 'Download the map as an OnlineWardleyMaps .owm file, ready to open in any Wardley mapping tool.',
+    descriptionFallback: 'Download the selected map as an OnlineWardleyMaps .owm file — the components inside its perimeter, ready to open in any Wardley mapping tool.',
     category: 'interchange',
     iconKey: 'wardley.export-owm',
-    surfaces: ['catalogue', 'palette', 'agent'],
+    surfaces: ['catalogue', 'contextual-toolbar', 'palette', 'agent'],
     order: SPECS.length + 1,
     scope: 'edgeless',
     defaultKeys: { mac: [], other: [] },
-    availability: 'always',
+    availability: 'selection',
     run: exportOwmFile,
     telemetry: { framework: 'wardley', element: 'board:export-owm' },
-    when: std => wardleyMapsOnBoard(std).length > 0,
+    when: std => wardleyMapsSelected(std).length > 0,
 };
 /**
  * The SVG FALLBACK import — the visual tier, named as such before the picker
@@ -439,4 +457,7 @@ export const wardleyCommandIcons = {
     'wardley.import-owm': wardleyImportOwmIcon,
     'wardley.export-owm': wardleyExportOwmIcon,
     'wardley.import-svg': wardleyImportSvgIcon,
+    // The senior button's 56×56 glyph, so `FrameworkDescriptor.iconKey` resolves
+    // through `getCommandIcon`.
+    'wardley.toolbar': wardleyToolbarIcon,
 };