@formicoidea/labre-framework-wardley 0.41.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, wardleyNodeLabelKey, 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
@@ -80,10 +81,6 @@ function backgroundVariantDefaults(gfx) {
         '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;
 function finish(gfx, id) {
     gfx.doc.captureSync();
     gfx.tool.setTool(DefaultTool);
@@ -160,15 +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 { 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]), cx + w / 2 + LABEL_GAP, cy - LABEL_H / 2);
+    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). */
@@ -193,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, translateKey(gfx.std, wardleyNodeLabelKey('pipeline'), 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]));
@@ -218,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, translateKey(gfx.std, wardleyNodeLabelKey('market'), 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]));
 }
 /**
@@ -282,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, translateKey(gfx.std, wardleyNodeLabelKey(kind), 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]));
 }
 /**
@@ -321,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.
@@ -391,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.
@@ -423,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,
 };

package/dist/element-view.d.ts

@@ -1,42 +1,28 @@
+import type { EditableBackgroundLabel, FrameworkBackgroundDef } from '@formicoidea/labre-core/blocks/surface';
+import { DeclaredBackgroundView } from '@formicoidea/labre-core/blocks/surface';
 import type { WardleyBackgroundElementModel } from '@formicoidea/labre-core/model';
-import type { EditorHost } from '@formicoidea/labre-core/std';
-import type { PointTestOptions } from '@formicoidea/labre-core/std/gfx';
-import { GfxElementModelView } from '@formicoidea/labre-core/std/gfx';
-export declare class WardleyView extends GfxElementModelView<WardleyBackgroundElementModel> {
+/**
+ * The Wardley map's view: the shared background gesture, aimed by the
+ * `WARDLEY_BACKGROUND` declaration.
+ *
+ * The in-place rename shipped here first and has moved to
+ * `DeclaredBackgroundView` (`@labre/affine-block-surface`) so that every
+ * framework background gets it rather than the two that got round to copying
+ * it — see issue #355. Nothing about the map's behaviour changed: the hit test
+ * reads the same declaration, through the same catalogue, and the guard below
+ * is the one thing this framework adds to it.
+ */
+export declare class WardleyView extends DeclaredBackgroundView<WardleyBackgroundElementModel> {
     static type: string;
-    /** The in-place `<input>` used to edit a label, or null when idle. */
-    private _labelEditor;
-    onCreated(): void;
-    onDestroyed(): void;
+    protected get def(): FrameworkBackgroundDef;
     /**
-     * The editable label under a MODEL-space point, or null.
+     * The declaration names the prop; this decides whether it may be WRITTEN.
      *
-     * Which labels exist, where they sit, what they SAY and which are editable
-     * all come from the declaration the renderer paints — one source, resolved
-     * through the same catalogue, so a label can never be drawn in one place
-     * and clicked in another, nor read one thing and open on another.
-     */
-    private _labelAt;
-    /**
-     * The map is SELECTED by its border (`WardleyBackgroundElementModel`), but
-     * its axis labels must still receive the double-click that renames them.
-     *
-     * So the two areas differ, and this is where they are allowed to: the pointer
-     * router asks the VIEW (`GfxViewEventManager`), and the view adds the zones
-     * the declaration draws its labels in. Picking is unaffected —
-     * `getElementByPoint` still asks the model, so a click in the middle of the
-     * map still goes to whatever the user put there.
-     */
-    includesPoint(x: number, y: number, options: PointTestOptions, host: EditorHost): boolean;
-    /** Double-click on a label → edit its text in place. */
-    private _onDblClick;
-    /**
-     * @param current the words currently DRAWN — which is the vocabulary, not
-     * `model[field]`, for a label the user has never renamed. Opening on the raw
-     * prop would show an empty box for a label that plainly reads "Evolution".
+     * A closed list, because since #73 an element preserves keys it does not
+     * declare: a typo in the declaration would otherwise persist a junk key onto
+     * every map it was double-clicked on.
      */
-    private _openLabelEditor;
-    private _closeLabelEditor;
+    protected labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
 }
 /**
  * Resize gating, from the primitive: the handles stay hidden until