@formicoidea/labre-framework-wardley 0.34.2 → 0.36.0

package/dist/actions.d.ts

@@ -1,42 +1,25 @@
 import { WardleyBackgroundElementModel, type WardleyBgVariant } from '@formicoidea/labre-core/model';
+import { Bound } from '@formicoidea/labre-core/global/gfx';
 import type { BlockStdScope } from '@formicoidea/labre-core/std';
 import { type GfxController } from '@formicoidea/labre-core/std/gfx';
 import { type WardleyExportBoard } from './export.js';
+import { type WardleyAreaShape, type WardleyArtefactKind } from './presets.js';
 /**
  * The single-circle node flavours: one connectable ellipse + a label to its
  * right, grouped. The glyph itself (anchor silhouette, ecosystem hatching,
  * method inner circle) is drawn by the node renderer from `kind`.
+ *
+ * A subset of {@link WardleyArtefactKind}, and named away from
+ * `WardleyNodeKind` on purpose: the model declares a type of that name with
+ * eleven values, and two homonyms of different cardinality — one of them the
+ * source of the semantic vocabulary — is a trap. The market, the pipeline and
+ * the Porter's-forces glyph are composites with creation functions of their
+ * own; the accelerator and the decelerator are not circles at all and place
+ * their label on the side their arrow points from
+ * ({@link createWardleyAccelerator}); the area is a zone with no label element
+ * at all ({@link createWardleyArea}); the handle is not an artefact.
  */
-declare const NODE_PRESETS: {
-    readonly component: {
-        readonly d: 18;
-        readonly fill: "#ffffff";
-        readonly label: string;
-    };
-    readonly anchor: {
-        readonly d: 18;
-        readonly fill: "#ffffff";
-        readonly label: string;
-    };
-    readonly ecosystem: {
-        readonly d: 40;
-        readonly fill: "#ffffff";
-        readonly label: "Ecosystem";
-    };
-    readonly method: {
-        readonly d: 35;
-        readonly fill: "#d9d9d9";
-        readonly label: "Component";
-    };
-};
-/**
- * The subset of {@link WardleyNodeKind} that the single-circle presets above
- * cover. Renamed away from `WardleyNodeKind` on purpose: the model declares a
- * type of that name with SEVEN values, and two homonyms of different
- * cardinality — one of them now the source of the semantic vocabulary — is a
- * trap. `WARDLEY_ROLE[kind]` below only compiles while this stays a subset.
- */
-export type WardleySingleCircleKind = keyof typeof NODE_PRESETS;
+export type WardleySingleCircleKind = Exclude<WardleyArtefactKind, 'market' | 'pipeline' | 'porter' | 'accelerator' | 'decelerator' | 'area'>;
 /** Create a wardley map background of the given variant, viewport-centered. */
 export declare function createWardleyBackground(gfx: GfxController, variant?: WardleyBgVariant): void;
 /**
@@ -63,6 +46,104 @@ export declare function createWardleyPipeline(gfx: GfxController): void;
  * everything is grouped into one object.
  */
 export declare function createWardleyMarket(gfx: GfxController): void;
+/**
+ * Create a Porter's-forces glyph: a white circle carrying ONE letter, pushed on
+ * from the four cardinal directions by solid red arrows, all grouped as one
+ * object.
+ *
+ * It marks an EXTERNAL competition force acting on the map — which is why the
+ * circle carries `wardley:porter` and nothing under `wardley:component`: it is
+ * not a link in the value chain, and no rule written about the chain has
+ * anything to say about a pressure applied from outside it.
+ *
+ * No label, and that is the notation rather than an omission: the letter says
+ * which force this is (R relative competition, L struggle for survival, E
+ * struggle to establish) and it is the circle's OWN inner text, so a
+ * double-click opens the native shape editor on it (`node/node-view.ts`). The
+ * four arrows are the glyph's own wiring — role-less filled red polygons,
+ * outside the rim — exactly as the market's triangle is its own.
+ */
+export declare function createWardleyPorter(gfx: GfxController): void;
+/**
+ * Create an accelerator or a decelerator: one fat native POLYGON and the words
+ * that say what it is, grouped like every other artefact.
+ *
+ * Not a link in the value chain, and not a pressure on it either: an annotation
+ * of the CLIMATE, saying that something is speeding evolution up (an arrow
+ * pointing right, towards commodity) or holding it back (the mirror, pointing
+ * left). Which way it points IS the notation, so the two are separate kinds
+ * with outlines of their own rather than one kind with a `rotate`.
+ *
+ * ## Where the words go, and why it is not always the right
+ *
+ * Every other single artefact on this canvas wears its name on its right,
+ * because a circle has no direction to disagree with. An arrow does. The
+ * reference puts the words on the side the arrow's SHAFT is on — right of an
+ * accelerator, left of a decelerator — so the reading runs into the arrow
+ * rather than across it, and the label is aligned towards it (left-aligned on
+ * the right, right-aligned on the left) so the words end against the shaft
+ * whatever their length.
+ *
+ * SemiBold, which no other Wardley label is: these two are annotations laid
+ * over a map that is already full of names, and the weight is what keeps the
+ * word readable as a remark ABOUT the map rather than as one more component.
+ */
+export declare function createWardleyAccelerator(gfx: GfxController, kind: 'accelerator' | 'decelerator'): void;
+/**
+ * Create an AREA: a translucent zone of the map, drawn as a rectangle or as a
+ * polygon whose corners the author then moves.
+ *
+ * One element and no group, which makes it the plainest creation site in this
+ * file — and the difference is the name. Every other artefact wears its name as
+ * a text element beside it, so every other artefact is a group of two. A zone's
+ * name belongs INSIDE the zone, so it is the shape's own inner text: created
+ * empty, opened by a double-click on the zone (`node/node-view.ts`), and set in
+ * a fit mode that never resizes the boundary around it.
+ *
+ * ## Why it is sent to the back
+ *
+ * A zone is drawn precisely OVER the components it groups, and the surface
+ * paints in index order: an area added last would sit on top of everything it
+ * surrounds — hiding it under a wash, and worse, intercepting every click meant
+ * for a component inside it. So the element is lowered the moment it exists,
+ * to the depth {@link wardleyAreaIndexOver} works out.
+ */
+export declare function createWardleyArea(gfx: GfxController, shape: WardleyAreaShape): void;
+/**
+ * One already-placed element, as {@link wardleyAreaIndexOver} needs to read it.
+ *
+ * Three fields and no model, so the placement can be reasoned about — and
+ * tested — without a document: what it is, where it is, and how deep.
+ */
+export interface WardleyStackedElement {
+    /** Fractional index. Sorts lexicographically, which IS the paint order. */
+    index: string;
+    /** Serialized box. */
+    xywh: string;
+    /** Whether this is a framework BACKGROUND — a map, a pool, a C4 board… */
+    isBackground: boolean;
+}
+/**
+ * How deep a freshly drawn zone goes: just ABOVE the framework backgrounds it
+ * covers, and below everything else. `null` means the back of the surface.
+ *
+ * "The back" alone was the first answer and it was wrong, as the recette of
+ * #213 found: a Wardley map is a framework BACKGROUND — an opaque one — so a
+ * zone sent behind the whole surface went behind the map and vanished. What a
+ * zone must be under is the artefacts it groups; what it must be over is the
+ * canvas they are drawn on. Those are two different depths, and only the first
+ * one is "the back".
+ *
+ * So: find the topmost background the zone actually OVERLAPS — the map it was
+ * drawn on, and not some other framework's board parked elsewhere on the same
+ * canvas — and mint a key between it and whatever sits directly above it. With
+ * no background under the zone at all there is nothing to clear, and the back
+ * of the surface is right again.
+ *
+ * `siblings` need not be sorted: fractional indexes sort lexicographically, so
+ * this sorts them itself and reads the paint order straight off the strings.
+ */
+export declare function wardleyAreaIndexOver(siblings: readonly WardleyStackedElement[], box: Bound): string | null;
 /**
  * Read an SVG the user picks as a SKETCH, and say what it cost.
  *
@@ -114,4 +195,3 @@ export declare function exportOwmFile(std: BlockStdScope): void;
  * the capability handed to it.
  */
 export declare function importOwmFile(std: BlockStdScope): Promise<void>;
-export {};

package/dist/actions.js

@@ -1,16 +1,17 @@
 import { backgroundSize, DefaultTool, 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, FontFamily, PointStyle, ShapeStyle, StrokeStyle, TextFitMode, WardleyBackgroundElementModel, } from '@formicoidea/labre-core/model';
+import { ConnectorMode, FontFamily, FontWeight, FrameworkBackgroundElementModel, PointStyle, ShapeStyle, StrokeStyle, TextFitMode, 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 { generateKeyBetween, 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 { ECOSYSTEM_LABEL, ECOSYSTEM_SIZE, HANDLE_SIZE, INERTIA_COLOR, INERTIA_SIZE, LABEL_DEFAULT, LABEL_FONT_SIZE, LABEL_GAP, LINK_GREY, LINK_STROKE_WIDTH, MARKET_DOT_RING, MARKET_DOT_SIZE, MARKET_DOT_STROKE_WIDTH, MARKET_LABEL, MARKET_LINK_COLOR, MARKET_LINK_WIDTH, MARKET_SIZE, METHOD_FILL, METHOD_LABEL, METHOD_SIZE, NODE_FILL, NODE_SIZE, NODE_STROKE, NODE_STROKE_WIDTH, PIPELINE_FILL, PIPELINE_HEIGHT, PIPELINE_LABEL, PIPELINE_WIDTH, WARDLEY_RED, } from './node/consts.js';
+import { HANDLE_SIZE, INERTIA_COLOR, INERTIA_SIZE, LABEL_FONT_SIZE, LABEL_GAP, LINK_GREY, LINK_STROKE_WIDTH, NODE_STROKE, PORTER_DEFAULT_LETTER, WARDLEY_RED, } from './node/consts.js';
+import { wardleyAreaBox, wardleyAreaProps, wardleyCanonicalBox, wardleyHandleBox, wardleyHandleProps, wardleyMarketDotBoxes, wardleyMarketDotProps, wardleyMarketLinkPairs, wardleyMarketLinkProps, WARDLEY_NODE_LABEL, WARDLEY_NODE_SIZE, wardleyNodeProps, wardleyPorterArrowProps, wardleyPorterArrows, wardleyPorterLetterProps, } from './presets.js';
 import { WARDLEY_ROLE } from './roles.js';
 /**
  * Standalone creation/activation actions for the Wardley toolbox — the
@@ -64,19 +65,13 @@ const BACKGROUND_VARIANT_DEFAULTS = {
 /** Height of the native free-text labels (Inter, size 18). */
 const LABEL_H = LABEL_FONT_SIZE + 8;
 /**
- * The single-circle node flavours: one connectable ellipse + a label to its
- * right, grouped. The glyph itself (anchor silhouette, ecosystem hatching,
- * method inner circle) is drawn by the node renderer from `kind`.
+ * Width of a label box, whatever it reads.
+ *
+ * A number rather than a measurement, which is why a RIGHT-aligned label has to
+ * subtract it: the box does not shrink to the words, so the only way to make
+ * the words end on a given edge is to start the box a full width before it.
  */
-const NODE_PRESETS = {
-    component: { d: NODE_SIZE, fill: NODE_FILL, label: LABEL_DEFAULT.component },
-    anchor: { d: NODE_SIZE, fill: NODE_FILL, label: LABEL_DEFAULT.anchor },
-    // Ecosystem: glyph = double border + hatched donut; connectors attach to
-    // this outer circle's center.
-    ecosystem: { d: ECOSYSTEM_SIZE, fill: NODE_FILL, label: ECOSYSTEM_LABEL },
-    // Method: the FILL color encodes the chosen method (editable).
-    method: { d: METHOD_SIZE, fill: METHOD_FILL, label: METHOD_LABEL },
-};
+const LABEL_W = 120;
 function finish(gfx, id) {
     gfx.doc.captureSync();
     gfx.tool.setTool(DefaultTool);
@@ -91,34 +86,30 @@ function group(gfx, ids) {
     });
     return result.groupId || ids[0];
 }
-/** Add a native ellipse wardley node centred on (cx, cy). */
-function addEllipseNode(surface, kind, cx, cy, d, fillColor, strokeWidth = NODE_STROKE_WIDTH, 
-// The market's three inner dots are the GLYPH's own wiring, not artefacts the
-// user placed — the same reason its triangle connectors carry no role. They
-// sit inside the market circle by construction, so a role would make every
-// market composite report an overlap with itself (W3).
-neutral = false) {
+/**
+ * Add a wardley node of one kind, at its canonical size, centred on (cx, cy).
+ *
+ * The APPEARANCE is {@link wardleyNodeProps}' and nothing else: the palette and
+ * the "Change type" dropdown read that one description, so a market drawn here
+ * and a component morphed into one are the same element (`presets.ts`).
+ *
+ * `extra` is for what a preset cannot carry — the Porter's-forces letter, which
+ * is CONTENT the author then edits, not a look. `wardleyMorphProps` strips
+ * `text` for exactly that reason, so a preset that wrote one would be a preset
+ * the morph has to un-write.
+ */
+function addNode(surface, kind, cx, cy, extra = {}) {
     return surface.addElement({
-        type: 'wardleyNode',
-        kind,
-        // Semantic identity (PF1): posted next to `kind`, which stays untouched
-        // and keeps driving the rendering.
-        role: neutral ? undefined : WARDLEY_ROLE[kind],
-        shapeType: 'ellipse',
-        filled: true,
-        fillColor,
-        strokeColor: NODE_STROKE,
-        strokeWidth,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        xywh: new Bound(cx - d / 2, cy - d / 2, d, d).serialize(),
+        ...wardleyNodeProps(kind, { xywh: wardleyCanonicalBox(kind, cx, cy) }),
+        ...extra,
     });
 }
 /** Add a native free-text label (same Inter family as the axis labels). */
-function addLabel(surface, text, x, y, textAlign = 'left') {
+function addLabel(surface, text, x, y, textAlign = 'left', fontWeight = FontWeight.Regular) {
     return surface.addElement({
         type: 'text',
         text,
+        fontWeight,
         // Semantic identity (PF1, revised in PF13.4): a Wardley label is a free
         // text element like any other, so its ROLE is the only thing that tells W3
         // it must not land on top of a node. A free text the user typed elsewhere
@@ -128,7 +119,7 @@ function addLabel(surface, text, x, y, textAlign = 'left') {
         fontSize: LABEL_FONT_SIZE,
         color: NODE_STROKE,
         textAlign,
-        xywh: new Bound(x, y, 120, LABEL_H).serialize(),
+        xywh: new Bound(x, y, LABEL_W, LABEL_H).serialize(),
     });
 }
 /** Create a wardley map background of the given variant, viewport-centered. */
@@ -171,10 +162,10 @@ export function createWardleyNode(gfx, kind) {
     const surface = gfx.surface;
     if (!surface)
         return;
-    const { d, fill, label } = NODE_PRESETS[kind];
+    const { w } = WARDLEY_NODE_SIZE[kind];
     const { centerX: cx, centerY: cy } = gfx.viewport;
-    const nodeId = addEllipseNode(surface, kind, cx, cy, d, fill);
-    const labelId = addLabel(surface, label, cx + d / 2 + LABEL_GAP, cy - LABEL_H / 2);
+    const nodeId = addNode(surface, kind, cx, cy);
+    const labelId = addLabel(surface, WARDLEY_NODE_LABEL[kind], cx + w / 2 + LABEL_GAP, cy - LABEL_H / 2);
     finish(gfx, group(gfx, [nodeId, labelId]));
 }
 /** Create an inertia bar (filled black rect). */
@@ -213,43 +204,15 @@ export function createWardleyPipeline(gfx) {
     if (!gfx.surface)
         return;
     const { centerX: cx, centerY: cy } = gfx.viewport;
-    const W = PIPELINE_WIDTH;
-    const H = PIPELINE_HEIGHT;
     const d = HANDLE_SIZE;
-    const top = cy - H / 2;
+    const top = cy - WARDLEY_NODE_SIZE.pipeline.h / 2;
     // Body: a WardleyNode rect, made non-connectable by `kind: 'pipeline'`.
-    const bodyId = gfx.surface.addElement({
-        type: 'wardleyNode',
-        kind: 'pipeline',
-        role: WARDLEY_ROLE.pipeline,
-        shapeType: 'rect',
-        filled: true,
-        fillColor: PIPELINE_FILL,
-        strokeColor: NODE_STROKE,
-        strokeWidth: NODE_STROKE_WIDTH,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        radius: 0,
-        xywh: new Bound(cx - W / 2, top, W, H).serialize(),
-    });
+    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({
-        type: 'wardleyNode',
-        kind: 'handle',
-        role: WARDLEY_ROLE.handle,
-        shapeType: 'rect',
-        filled: true,
-        fillColor: NODE_FILL,
-        strokeColor: NODE_STROKE,
-        strokeWidth: NODE_STROKE_WIDTH,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        radius: 0,
-        xywh: new Bound(cx - d / 2, top - d / 2, d, d).serialize(),
-    });
+    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, PIPELINE_LABEL, cx - 60, top - d / 2 - LABEL_H - LABEL_GAP, 'center');
+    const labelId = addLabel(gfx.surface, WARDLEY_NODE_LABEL.pipeline, cx - 60, top - d / 2 - LABEL_H - LABEL_GAP, 'center');
     // Nested groups: (handle + label), then (body + that group).
     const innerId = group(gfx, [handleId, labelId]);
     finish(gfx, group(gfx, [bodyId, innerId]));
@@ -266,37 +229,160 @@ export function createWardleyMarket(gfx) {
     if (!surface)
         return;
     const { centerX: cx, centerY: cy } = gfx.viewport;
-    const R = MARKET_SIZE / 2;
-    const rho = MARKET_DOT_RING;
-    const sin60 = Math.sqrt(3) / 2;
+    const R = WARDLEY_NODE_SIZE.market.w / 2;
     // Outer circle = the market node (connectable, center-only).
-    const circleId = addEllipseNode(surface, 'market', cx, cy, MARKET_SIZE, NODE_FILL);
+    const circleId = addNode(surface, 'market', cx, cy);
     // 3 inner component nodes (thick border, no label) at the triangle vertices.
-    const verts = [
-        [0, -rho],
-        [rho * sin60, rho / 2],
-        [-rho * sin60, rho / 2],
-    ];
-    const dotIds = verts.map(([vx, vy]) => addEllipseNode(surface, 'component', cx + vx, cy + vy, MARKET_DOT_SIZE, NODE_FILL, MARKET_DOT_STROKE_WIDTH, true));
+    const dotIds = wardleyMarketDotBoxes(cx, cy).map(xywh => surface.addElement(wardleyMarketDotProps({ xywh })));
     // Triangle: 3 attached connectors (auto-route center-to-center, clipped).
-    const connIds = [
-        [dotIds[0], dotIds[1]],
-        [dotIds[1], dotIds[2]],
-        [dotIds[2], dotIds[0]],
-    ].map(([a, b]) => surface.addElement({
-        type: 'connector',
-        mode: ConnectorMode.Straight,
-        source: { id: a },
-        target: { id: b },
-        stroke: MARKET_LINK_COLOR,
-        strokeStyle: StrokeStyle.Solid,
-        strokeWidth: MARKET_LINK_WIDTH,
-        frontEndpointStyle: PointStyle.None,
-        rearEndpointStyle: PointStyle.None,
-    }));
-    const labelId = addLabel(surface, MARKET_LABEL, cx + R + LABEL_GAP, cy - LABEL_H / 2);
+    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);
     finish(gfx, group(gfx, [circleId, ...dotIds, ...connIds, labelId]));
 }
+/**
+ * Create a Porter's-forces glyph: a white circle carrying ONE letter, pushed on
+ * from the four cardinal directions by solid red arrows, all grouped as one
+ * object.
+ *
+ * It marks an EXTERNAL competition force acting on the map — which is why the
+ * circle carries `wardley:porter` and nothing under `wardley:component`: it is
+ * not a link in the value chain, and no rule written about the chain has
+ * anything to say about a pressure applied from outside it.
+ *
+ * No label, and that is the notation rather than an omission: the letter says
+ * which force this is (R relative competition, L struggle for survival, E
+ * struggle to establish) and it is the circle's OWN inner text, so a
+ * double-click opens the native shape editor on it (`node/node-view.ts`). The
+ * four arrows are the glyph's own wiring — role-less filled red polygons,
+ * outside the rim — exactly as the market's triangle is its own.
+ */
+export function createWardleyPorter(gfx) {
+    const surface = gfx.surface;
+    if (!surface)
+        return;
+    const { centerX: cx, centerY: cy } = gfx.viewport;
+    const circleId = addNode(surface, 'porter', cx, cy, wardleyPorterLetterProps(PORTER_DEFAULT_LETTER));
+    const arrowIds = wardleyPorterArrows(cx, cy).map(arrow => surface.addElement(wardleyPorterArrowProps(arrow)));
+    finish(gfx, group(gfx, [circleId, ...arrowIds]));
+}
+/**
+ * Create an accelerator or a decelerator: one fat native POLYGON and the words
+ * that say what it is, grouped like every other artefact.
+ *
+ * Not a link in the value chain, and not a pressure on it either: an annotation
+ * of the CLIMATE, saying that something is speeding evolution up (an arrow
+ * pointing right, towards commodity) or holding it back (the mirror, pointing
+ * left). Which way it points IS the notation, so the two are separate kinds
+ * with outlines of their own rather than one kind with a `rotate`.
+ *
+ * ## Where the words go, and why it is not always the right
+ *
+ * Every other single artefact on this canvas wears its name on its right,
+ * because a circle has no direction to disagree with. An arrow does. The
+ * reference puts the words on the side the arrow's SHAFT is on — right of an
+ * accelerator, left of a decelerator — so the reading runs into the arrow
+ * rather than across it, and the label is aligned towards it (left-aligned on
+ * the right, right-aligned on the left) so the words end against the shaft
+ * whatever their length.
+ *
+ * SemiBold, which no other Wardley label is: these two are annotations laid
+ * over a map that is already full of names, and the weight is what keeps the
+ * word readable as a remark ABOUT the map rather than as one more component.
+ */
+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);
+    finish(gfx, group(gfx, [nodeId, labelId]));
+}
+/**
+ * Create an AREA: a translucent zone of the map, drawn as a rectangle or as a
+ * polygon whose corners the author then moves.
+ *
+ * One element and no group, which makes it the plainest creation site in this
+ * file — and the difference is the name. Every other artefact wears its name as
+ * a text element beside it, so every other artefact is a group of two. A zone's
+ * name belongs INSIDE the zone, so it is the shape's own inner text: created
+ * empty, opened by a double-click on the zone (`node/node-view.ts`), and set in
+ * a fit mode that never resizes the boundary around it.
+ *
+ * ## Why it is sent to the back
+ *
+ * A zone is drawn precisely OVER the components it groups, and the surface
+ * paints in index order: an area added last would sit on top of everything it
+ * surrounds — hiding it under a wash, and worse, intercepting every click meant
+ * for a component inside it. So the element is lowered the moment it exists,
+ * to the depth {@link wardleyAreaIndexOver} works out.
+ */
+export function createWardleyArea(gfx, shape) {
+    const surface = gfx.surface;
+    if (!surface)
+        return;
+    const { centerX: cx, centerY: cy } = gfx.viewport;
+    const xywh = wardleyAreaBox(shape, cx, cy);
+    const id = surface.addElement(wardleyAreaProps(shape, { xywh }));
+    const model = surface.getElementById(id);
+    if (model) {
+        const over = wardleyAreaIndexOver(stackedElementsOf(surface, id), Bound.deserialize(xywh));
+        // `null` is "nothing under it": the back of the surface, minted by the
+        // layer itself so an empty board gets the layer's own initial index rather
+        // than a key invented here.
+        model.index = over ?? gfx.layer.getReorderedIndex(model, 'back');
+    }
+    finish(gfx, id);
+}
+/** The top-level canvas elements of a surface, minus the one being placed. */
+function stackedElementsOf(surface, exclude) {
+    return surface.elementModels
+        .filter(model => model.id !== exclude && model.group === null)
+        .map(model => ({
+        index: model.index,
+        xywh: model.xywh,
+        isBackground: model instanceof FrameworkBackgroundElementModel,
+    }));
+}
+/**
+ * How deep a freshly drawn zone goes: just ABOVE the framework backgrounds it
+ * covers, and below everything else. `null` means the back of the surface.
+ *
+ * "The back" alone was the first answer and it was wrong, as the recette of
+ * #213 found: a Wardley map is a framework BACKGROUND — an opaque one — so a
+ * zone sent behind the whole surface went behind the map and vanished. What a
+ * zone must be under is the artefacts it groups; what it must be over is the
+ * canvas they are drawn on. Those are two different depths, and only the first
+ * one is "the back".
+ *
+ * So: find the topmost background the zone actually OVERLAPS — the map it was
+ * drawn on, and not some other framework's board parked elsewhere on the same
+ * canvas — and mint a key between it and whatever sits directly above it. With
+ * no background under the zone at all there is nothing to clear, and the back
+ * of the surface is right again.
+ *
+ * `siblings` need not be sorted: fractional indexes sort lexicographically, so
+ * this sorts them itself and reads the paint order straight off the strings.
+ */
+export function wardleyAreaIndexOver(siblings, box) {
+    const stack = [...siblings].sort((a, b) => a.index < b.index ? -1 : a.index > b.index ? 1 : 0);
+    // The LAST match, which is the topmost: a board with two maps on it gets the
+    // zone above the one it is actually drawn over, whichever was drawn first.
+    const under = stack.reduce((found, element, at) => element.isBackground &&
+        Bound.deserialize(element.xywh).isOverlapWithBound(box)
+        ? at
+        : found, -1);
+    if (under < 0)
+        return null;
+    // `null` for the upper bound when the background is the topmost element
+    // there is — `generateKeyBetween` reads that as "append after".
+    return generateKeyBetween(stack[under].index, stack[under + 1]?.index ?? null);
+}
 /**
  * Read an SVG the user picks as a SKETCH, and say what it cost.
  *

package/dist/commands-manifest.js

@@ -119,6 +119,46 @@ export const wardleyCommandsManifest = [
         scope: 'edgeless',
         defaultKeys: { mac: ['w', 'i'], other: ['w', 'i'] },
     },
+    {
+        id: 'wardley.addPorter',
+        owner: 'wardley',
+        labelKey: 'com.labre.commands.wardley.addPorter',
+        labelFallback: "Porter's forces",
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+    },
+    {
+        id: 'wardley.addAccelerator',
+        owner: 'wardley',
+        labelKey: 'com.labre.commands.wardley.addAccelerator',
+        labelFallback: 'Accelerator',
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+    },
+    {
+        id: 'wardley.addDecelerator',
+        owner: 'wardley',
+        labelKey: 'com.labre.commands.wardley.addDecelerator',
+        labelFallback: 'Decelerator',
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+    },
+    {
+        id: 'wardley.addAreaRect',
+        owner: 'wardley',
+        labelKey: 'com.labre.commands.wardley.addAreaRect',
+        labelFallback: 'Area (rectangle)',
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+    },
+    {
+        id: 'wardley.addAreaPolygon',
+        owner: 'wardley',
+        labelKey: 'com.labre.commands.wardley.addAreaPolygon',
+        labelFallback: 'Area (polygon)',
+        scope: 'edgeless',
+        defaultKeys: { mac: [], other: [] },
+    },
     {
         id: 'wardley.importOwm',
         owner: 'wardley',

package/dist/commands.d.ts

@@ -1,8 +1,25 @@
 import type { CommandDescriptor } from '@formicoidea/labre-core/std';
 import type { TemplateResult } from 'lit';
 /**
- * The Wardley registry: the thirteen toolbox entries, then the two directions
+ * The Wardley registry: the eighteen toolbox entries, then the two directions
  * of the OWM DSL and the SVG fallback (`docs/adr/0012`).
+ *
+ * ## Nineteen nominations, and the curation decision behind them
+ *
+ * `addPorter` spent the last seat of ADR 0014 R4's `SENIOR_MENU_CAP + 1`
+ * budget, and `addAccelerator` / `addDecelerator` are the two past it. The PO
+ * made the call on 2026-09-03 (Amendment 2026-09-03 under R4): **every Wardley
+ * artefact nominates the row**. The row itself is unchanged — thirteen
+ * arbitrated seats plus "More artefacts…", the cap of fourteen it has had since
+ * the OWM pair tipped this framework over — so what the decision buys is that
+ * a newly-drawn artefact is ELIGIBLE for a seat, and recency and frequency
+ * decide who gets one. Nothing becomes unreachable: the catalogue lists
+ * everything, which is the registry's own invariant.
+ *
+ * `addAreaRect` and `addAreaPolygon` are the two after those, and they land
+ * under that same amendment rather than reopening it: they nominate like every
+ * other Wardley artefact, the row is still thirteen arbitrated seats plus "More
+ * artefacts…", and the catalogue grows by a section of its own.
  */
 export declare const wardleyCommands: CommandDescriptor[];
 /** `iconKey` → template. Never travels through either manifest (ADR 0008). */