@formicoidea/labre-framework-wardley 0.30.1 → 0.32.0

package/dist/rules.js

@@ -0,0 +1,270 @@
+import { WARDLEY_BACKGROUND } from './background.js';
+import { WARDLEY_ROLE, WARDLEY_ROLES } from './roles.js';
+/**
+ * Wardley validation rules (PF13.4 / PF13.5 / PF13.6).
+ *
+ * DATA owned by the framework, versioned per rule: the engine
+ * (`@labre/affine-block-surface`) knows how to evaluate a FAMILY, never a
+ * concrete rule. Adding a Wardley rule is adding an entry to this array.
+ *
+ * Registered from the flag-gated `WardleyViewExtension`, so switching the
+ * Wardley flag off removes the rules with the rest of the tooling — already
+ * drawn maps keep rendering, they simply stop being checked (see
+ * `docs/adr/0009`).
+ *
+ * ## The pilot rule is gone
+ *
+ * `wardley.component-outside-map` was the tracer bullet's rule: it existed to
+ * prove the engine, the affordance, the exceptions and the profiles could work
+ * end to end, never because a Wardley practitioner asked for it. Parking a node
+ * in the margin while you think is normal work, and PO decision of 01/08/2026
+ * removed it the moment there were real rules for the machinery to carry.
+ * Nothing was left behind: every test that exercised the pipework through it
+ * now exercises it through W1, W2 or W3.
+ *
+ * ## Severity, and a hole that is named rather than papered over
+ *
+ * W1 and W2 are the two the architect would put at `blocking-overridable`. They
+ * are declared `warning`, because NOTHING downstream implements a blocking
+ * level: no gesture is refused anywhere in this library, so shipping the value
+ * would be data claiming an effect that does not exist. The severity moves to
+ * `blocking-overridable` in the profiles, in one line each, the day the gesture
+ * refusal lands. Building it was explicitly out of this slice.
+ */
+/**
+ * **W1** — a change arrow may not point against the sense of evolution.
+ *
+ * The whole grammar of a Wardley map is that things move left to right: a red
+ * arrow pointing back towards Genesis says the opposite of what the map means.
+ * Written on `wardley:change-arrow`, the role PF13.4 puts on the arrow at
+ * creation — value-chain links are a different role and are never touched.
+ *
+ * The 30° dead zone is deliberate. An arrow drawn straight up a value chain is
+ * neither with evolution nor against it, and one drawn slightly up-and-back is
+ * a hand that slipped, not a claim about the world. Only an arrow genuinely
+ * heading back — more than 120° off the axis' forward sense — is one.
+ */
+const changeArrowAgainstEvolution = {
+    id: 'wardley.change-arrow-against-evolution',
+    framework: 'wardley',
+    family: 'orientation-against-axis',
+    severity: 'warning',
+    appliesTo: WARDLEY_ROLE.changeArrow,
+    roles: WARDLEY_ROLES,
+    messageKey: 'com.labre.wardley.validation.change-arrow-against-evolution',
+    messageFallback: 'This change arrow points against evolution.',
+    suggestionKey: 'com.labre.wardley.validation.change-arrow-against-evolution.suggestion',
+    suggestionFallback: 'Evolution runs left to right — turn the arrow towards the commodity end, or draw a dependency instead.',
+    version: 1,
+    backgroundRole: WARDLEY_ROLE.map,
+    // The frame's own declaration, carried as data exactly like `roles` is: it is
+    // where "which way does evolution run" is written, and the engine reads it
+    // rather than knowing anything about Wardley.
+    background: WARDLEY_BACKGROUND,
+    against: { axis: 'evolution', toleranceDeg: 30 },
+};
+/**
+ * **W2** — the inertia bar straddles a phase transition.
+ *
+ * > "The horizontal position of an inertia bar is only valid if it is ASTRIDE
+ * > two evolution phases, that is, superimposed on a dashed vertical axis."
+ * > — the PO, spelling the rule out on the recette of 02/08/2026
+ *
+ * Inertia is resistance to crossing a frontier. The bar is the frontier being
+ * refused, so it is drawn ON the divider; a bar parked in the middle of a phase
+ * marks nothing at all and becomes a black rectangle.
+ *
+ * ## What this rule used to ask, and no longer does
+ *
+ * Until this version it ALSO demanded a dependency under the bar, and reported
+ * that half first ("This inertia bar is not drawn on a dependency."). That was
+ * our reading of inertia, not the PO's rule, and it was wrong in both
+ * directions: a bar alone on a divider — a perfectly ordinary way to say "this
+ * whole column is stuck" — was flagged, while nothing in the sentence pointed at
+ * the position that actually decides the verdict. The carrier condition is gone
+ * entirely, with the second message that existed only to tell the two halves
+ * apart. One condition, one sentence.
+ *
+ * ## "Astride", as geometry
+ *
+ * The engine takes the bar's own horizontal EXTENT and asks whether it
+ * intersects the transition band — the divider widened by the map's declared
+ * `transitionBandWidth` (see {@link AttachmentDef.boundaryAxis}). That single
+ * overlap test says both halves of "superimposed on the axis": a bar wide enough
+ * to cover the divider genuinely has the line running through it, and a bar too
+ * thin to cover anything (the toolbox draws it eight units wide) is accepted
+ * inside the band the map itself declares around the frontier — Wardley's zone
+ * of punctuated equilibrium, where inertia lives.
+ *
+ * Measured on the extent rather than on the centre because "superimposed on the
+ * line" is a statement about ink; measured against a band declared as a RATIO of
+ * the plot because the same gesture must get the same verdict on a map somebody
+ * resized (the lesson of the 01/08/2026 recette).
+ */
+const inertiaOffTransition = {
+    id: 'wardley.inertia-off-transition',
+    framework: 'wardley',
+    family: 'attachment',
+    severity: 'warning',
+    appliesTo: WARDLEY_ROLE.inertia,
+    roles: WARDLEY_ROLES,
+    // ONE sentence, because there is now one condition. The key is the rule's own
+    // id: the two keys it replaces named halves of a rule that no longer has any.
+    messageKey: 'com.labre.wardley.validation.inertia-off-transition',
+    messageFallback: 'This inertia bar sits inside a phase, not astride a phase transition.',
+    suggestionKey: 'com.labre.wardley.validation.inertia-off-transition.suggestion',
+    suggestionFallback: 'Inertia bites at a frontier — slide the bar sideways until it sits astride the dashed line between two evolution phases.',
+    // 3: the carrier condition is gone and the position is judged on the bar's
+    // extent — a different verdict on the same map, so a new version.
+    version: 3,
+    backgroundRole: WARDLEY_ROLE.map,
+    background: WARDLEY_BACKGROUND,
+    attachment: {
+        boundaryAxis: 'evolution',
+    },
+};
+/**
+ * **W3** — nodes and labels must not sit on top of each other.
+ *
+ * A readability rule, not a semantic one, which is why it is the softest of the
+ * three: a map you cannot read is useless, but a momentary overlap while you
+ * drag things into place is not a mistake.
+ *
+ * The four declared combinations are the ones that actually make a map
+ * illegible. Node/node hides an artefact outright; label/label and label/node
+ * make a name unreadable or attach it to the wrong thing; label/link is the one
+ * everybody hits, a name crossed out by the dependency running under it.
+ *
+ * Link/link is deliberately ABSENT: dependencies cross all the time on a real
+ * value chain, and that is the map working, not the map broken.
+ *
+ * ## Calibration (PO acceptance, 01/08/2026)
+ *
+ * Shipped, the rule was noisy in two ways the corpus could not see, because its
+ * fixtures were boxes rather than words:
+ *
+ * 1. a link crossing the EMPTY MARGIN of a label raised label/link. A label is
+ *    created 120–200 units wide whatever it says, so a short name left-aligned
+ *    in one leaves most of its box blank. Fixed where the mistake was: the
+ *    label role is `kind: 'text'`, so the engine measures the ink and not the
+ *    box (`textInkBound`).
+ * 2. two labels whose WORDS are nowhere near each other raised label/label,
+ *    for the same reason and with the same fix.
+ *
+ * `minPenetration` is what remains: not every touch is a collision. **4 model
+ * units** — under a quarter of the 18-unit node, a sixth of the 26-unit label
+ * line, and about the width of a dependency's own stroke. A link grazing the
+ * top of a name and two names whose last and first letter share a hair are
+ * silent; a link through the middle of a name scores half its line height (13)
+ * and a name written across a node scores the height of the letters, so both
+ * are still reported with room to spare.
+ *
+ * It also absorbs the declared imprecision of the width approximation, which is
+ * on the same scale — measured against the real renderer over 28 names, the
+ * engine's per-character table reads between 11 % narrow and dead on, never
+ * wide — and points the same way, towards silence.
+ *
+ * IN RESERVE, if label/link is still noisy after this (PO, 01/08/2026): an
+ * ANGLE criterion — only a link crossing a name roughly PERPENDICULARLY strikes
+ * it out, one running along it at a shallow angle mostly runs beside it. It
+ * would be declared here as data, exactly like the threshold, and evaluated by
+ * the family. Not built: nobody has yet seen the noise it would remove.
+ */
+const overlappingArtefacts = {
+    id: 'wardley.overlapping-artefacts',
+    framework: 'wardley',
+    family: 'no-overlap',
+    severity: 'warning',
+    // No `appliesTo`: this rule has no single subject role — the subjects are the
+    // pairs below, and naming one of them here would be data that lies.
+    roles: WARDLEY_ROLES,
+    messageKey: 'com.labre.wardley.validation.overlapping-artefacts',
+    messageFallback: 'These two overlap and make the map harder to read.',
+    suggestionKey: 'com.labre.wardley.validation.overlapping-artefacts.suggestion',
+    suggestionFallback: 'Move one of them aside.',
+    // 2: measured on the ink of a label rather than on its creation box, and
+    // calibrated with a penetration threshold — the same mistakes, fewer of the
+    // things that were never mistakes.
+    version: 2,
+    // Not a frame the rule measures against — an overlap is an overlap wherever
+    // it happens — but the map a finding is ATTRIBUTED to, so the arbitration
+    // "ignore this rule on the whole map" has one map to be written on.
+    backgroundRole: WARDLEY_ROLE.map,
+    overlap: [
+        [WARDLEY_ROLE.component, WARDLEY_ROLE.component],
+        [WARDLEY_ROLE.label, WARDLEY_ROLE.label],
+        [WARDLEY_ROLE.label, WARDLEY_ROLE.component],
+        [WARDLEY_ROLE.label, WARDLEY_ROLE.dependency],
+    ],
+    // How deep a collision has to be before it is one. See the header.
+    minPenetration: 4,
+};
+/**
+ * **W4** — a provider may not be positioned higher than its consumer.
+ *
+ * The value chain is the whole grammar of the map: the user sits at the top,
+ * each component rests on the components below it, and value flows back up. A
+ * dependency drawn from a component to something ABOVE it says the opposite of
+ * what the map means — either the link was drawn the wrong way round, or one of
+ * the two nodes is in the wrong place.
+ *
+ * ## The rule this one could not have been before `docs/adr/0010`
+ *
+ * W4 reads the persisted `source → target` pair of the edge, and that pair only
+ * became a STATEMENT the day the three mechanisms of that ADR landed: the link
+ * tool announces which way to drag (M1), a typed edge shows its orientation on
+ * hover and selection (M2), and the user can reverse it in one gesture (M3).
+ * Before them the direction was a by-product of which end the finger landed on
+ * first, and a rule on top of it would have spent the validation platform's
+ * credibility on its first false positive.
+ *
+ * The alternative — deriving the direction from the y coordinates — is not a
+ * cheaper W4, it is no W4 at all: the rule would compare the layout against
+ * itself and could never fire.
+ *
+ * ## The violation IS the affordance
+ *
+ * Nothing normalises the direction at creation, deliberately. An edge drawn
+ * upside-down raises this finding on the spot, and the user resolves it their
+ * way: drag the node, or reverse the relation. Either resolution is theirs.
+ *
+ * ## Tolerance
+ *
+ * 2% of the map's height, as a ratio and never as a number of units (the lesson
+ * of the 01/08/2026 recette, already learned by the equilibrium zone). Two
+ * components drawn level are not a mistake — a chain gets lined up before it
+ * gets spread out — so the rule only speaks when one is genuinely under the
+ * other. On the 900-high reference map that is 18 units, about the diameter of
+ * a component node.
+ */
+const providerAboveConsumer = {
+    id: 'wardley.provider-above-consumer',
+    framework: 'wardley',
+    family: 'relative-order-along-axis',
+    severity: 'warning',
+    // No `appliesTo`: the subject of this rule is a RELATION, and the role that
+    // names it is declared where the family reads it — naming one of the three
+    // indicted elements here would be data that lies.
+    roles: WARDLEY_ROLES,
+    messageKey: 'com.labre.wardley.validation.provider-above-consumer',
+    messageFallback: 'This component sits above the one that depends on it.',
+    suggestionKey: 'com.labre.wardley.validation.provider-above-consumer.suggestion',
+    suggestionFallback: 'Needs run downwards on a Wardley map: move the provider below its consumer — or, if the link was drawn the wrong way round, reverse it.',
+    version: 1,
+    backgroundRole: WARDLEY_ROLE.map,
+    background: WARDLEY_BACKGROUND,
+    relativeOrder: {
+        edgeRole: WARDLEY_ROLE.dependency,
+        axis: 'value-chain',
+        // Tier 2 of ADR 0010: the verb of `wardley:dependency` is "depends on", so
+        // its source is the CONSUMER and sits higher on the visibility axis.
+        expect: 'source-ahead',
+        toleranceRatio: 0.02,
+    },
+};
+export const WARDLEY_RULES = [
+    changeArrowAgainstEvolution,
+    inertiaOffTransition,
+    overlappingArtefacts,
+    providerAboveConsumer,
+];

package/dist/templates/index.js

@@ -1,8 +1,15 @@
 import { makeTemplateSnapshot, surfaceText, } from '@formicoidea/labre-core/gfx/template';
 import { ConnectorMode, FontFamily, PointStyle, ShapeStyle, StrokeStyle, TextAlign, } from '@formicoidea/labre-core/model';
-import { REF_WIDTH } from '../consts';
-import { wardleyMaps } from './maps';
-import { ECOSYSTEM_SIZE, HANDLE_SIZE, INERTIA_COLOR, INERTIA_SIZE, LABEL_FONT_SIZE, LINK_GREY, LINK_STROKE_WIDTH, MARKET_DOT_RING, MARKET_DOT_SIZE, MARKET_DOT_STROKE_WIDTH, MARKET_LINK_COLOR, MARKET_LINK_WIDTH, MARKET_SIZE, METHOD_FILL, METHOD_SIZE, NODE_FILL, NODE_SIZE, NODE_STROKE, NODE_STROKE_WIDTH, PIPELINE_FILL, PIPELINE_HEIGHT, PIPELINE_WIDTH, WARDLEY_RED, } from '../node/consts';
+import { REF_WIDTH } from '../consts.js';
+import { WARDLEY_ROLE } from '../roles.js';
+import { wardleyMaps } from './maps.js';
+import { ECOSYSTEM_SIZE, HANDLE_SIZE, INERTIA_COLOR, INERTIA_SIZE, LABEL_FONT_SIZE, LINK_GREY, LINK_STROKE_WIDTH, MARKET_DOT_RING, MARKET_DOT_SIZE, MARKET_DOT_STROKE_WIDTH, MARKET_LINK_COLOR, MARKET_LINK_WIDTH, MARKET_SIZE, METHOD_FILL, METHOD_SIZE, NODE_FILL, NODE_SIZE, NODE_STROKE, NODE_STROKE_WIDTH, PIPELINE_FILL, PIPELINE_HEIGHT, PIPELINE_WIDTH, WARDLEY_RED, } from '../node/consts.js';
+/**
+ * Verbatim copy of `BACKGROUND_VARIANT_DEFAULTS` in `../actions.ts` — see the
+ * TODO there: both copies write English prose into the document for the two
+ * value-chain variants, and both go away together when the variant becomes
+ * part of the declaration.
+ */
 const VARIANT_DEFAULTS = {
     classic: {},
     opportunity: {
@@ -23,10 +30,16 @@ const bg = (variant, w = REF_WIDTH) => {
     return { type: 'wardley', variant, ...VARIANT_DEFAULTS[variant], xywh: `[0,0,${w},${h}]` };
 };
 /** A wardley node ellipse positioned by top-left. */
-function node(kind, x, y, d = NODE_SIZE, fill = NODE_FILL, strokeWidth = NODE_STROKE_WIDTH) {
+function node(kind, x, y, d = NODE_SIZE, fill = NODE_FILL, strokeWidth = NODE_STROKE_WIDTH, 
+// Neutral for the market's inner dots, exactly as `createWardleyMarket` does:
+// glyph wiring, not artefacts.
+neutral = false) {
     return {
         type: 'wardleyNode',
         kind,
+        // A template must produce the same typed artefacts as the toolbox, so a
+        // map started from a preset validates like a hand-drawn one.
+        role: neutral ? undefined : WARDLEY_ROLE[kind],
         shapeType: 'ellipse',
         filled: true,
         fillColor: fill,
@@ -41,6 +54,7 @@ function label(x, y, str, align = 'left') {
     return {
         type: 'text',
         text: surfaceText(str),
+        role: WARDLEY_ROLE.label,
         color: NODE_STROKE,
         fontFamily: FontFamily.Inter,
         fontSize: LABEL_FONT_SIZE,
@@ -48,15 +62,35 @@ function label(x, y, str, align = 'left') {
         xywh: `[${x},${y},140,26]`,
     };
 }
+/**
+ * A Wardley connector for the palette samples.
+ *
+ * `evolution` is the ONE predicate that decides what the stroke means, here and
+ * in `maps.ts` alike — `docs/adr/0010` § Compatibility. The two kits used to
+ * test different things (`opts.red` here, `o.arrow` there), which was a style
+ * inconsistency until W4 started reading these edges and became a SEMANTIC one:
+ * what a rule governs must not depend on which authoring helper a template
+ * borrowed. Colour is a consequence of the meaning, never its source.
+ *
+ * `typed: false` drops the role altogether — for a sample that makes no claim
+ * about anything (see the "Link" swatch below).
+ */
 function connect(source, target, opts = {}) {
+    const role = opts.evolution
+        ? WARDLEY_ROLE.changeArrow
+        : WARDLEY_ROLE.dependency;
     return {
         type: 'connector',
         mode: ConnectorMode.Straight,
-        stroke: opts.red ? WARDLEY_RED : LINK_GREY,
-        strokeStyle: opts.red ? StrokeStyle.Dash : StrokeStyle.Solid,
+        // A template must produce the same typed artefacts as the toolbox, or a map
+        // started from a preset would validate differently from a hand-drawn one.
+        // `undefined` writes nothing: a neutral stroke keeps no `role` key.
+        role: opts.typed === false ? undefined : role,
+        stroke: opts.evolution ? WARDLEY_RED : LINK_GREY,
+        strokeStyle: opts.evolution ? StrokeStyle.Dash : StrokeStyle.Solid,
         strokeWidth: LINK_STROKE_WIDTH,
         frontEndpointStyle: PointStyle.None,
-        rearEndpointStyle: opts.red ? PointStyle.Triangle : PointStyle.None,
+        rearEndpointStyle: opts.evolution ? PointStyle.Triangle : PointStyle.None,
         source,
         target,
     };
@@ -64,6 +98,7 @@ function connect(source, target, opts = {}) {
 const inertia = (x = 0, y = 0) => ({
     type: 'shape',
     shapeType: 'rect',
+    role: WARDLEY_ROLE.inertia,
     filled: true,
     fillColor: INERTIA_COLOR,
     strokeColor: INERTIA_COLOR,
@@ -80,6 +115,7 @@ function pipeline() {
         body: {
             type: 'wardleyNode',
             kind: 'pipeline',
+            role: WARDLEY_ROLE.pipeline,
             shapeType: 'rect',
             filled: true,
             fillColor: PIPELINE_FILL,
@@ -93,6 +129,7 @@ function pipeline() {
         handle: {
             type: 'wardleyNode',
             kind: 'handle',
+            role: WARDLEY_ROLE.handle,
             shapeType: 'rect',
             filled: true,
             fillColor: NODE_FILL,
@@ -116,7 +153,9 @@ function market() {
         [rho * sin60, rho / 2],
         [-rho * sin60, rho / 2],
     ];
-    const dotAt = (vx, vy) => node('component', c + vx - MARKET_DOT_SIZE / 2, c + vy - MARKET_DOT_SIZE / 2, MARKET_DOT_SIZE, NODE_FILL, MARKET_DOT_STROKE_WIDTH);
+    const dotAt = (vx, vy) => node('component', c + vx - MARKET_DOT_SIZE / 2, c + vy - MARKET_DOT_SIZE / 2, MARKET_DOT_SIZE, NODE_FILL, MARKET_DOT_STROKE_WIDTH, true);
+    // Neutral on purpose: the triangle is the market glyph's own wiring, not a
+    // dependency the user drew (same rule as `createWardleyMarket`).
     const tri = (a, b) => ({
         type: 'connector',
         mode: ConnectorMode.Straight,
@@ -165,7 +204,12 @@ export const wardleyTemplateCategory = {
         tpl('Pipeline', `<svg ${ATTRS} fill="none"><rect x="34" y="40" width="66" height="14" fill="#fff" stroke="#1f2328"/><rect x="60" y="33" width="14" height="14" fill="#fff" stroke="#1f2328"/></svg>`, pipeline()),
         tpl('Market', `<svg ${ATTRS} fill="none"><circle cx="67" cy="40" r="16" fill="#fff" stroke="#1f2328"/><circle cx="67" cy="30" r="3.5" fill="#fff" stroke="#1f2328" stroke-width="1.5"/><circle cx="75" cy="46" r="3.5" fill="#fff" stroke="#1f2328" stroke-width="1.5"/><circle cx="59" cy="46" r="3.5" fill="#fff" stroke="#1f2328" stroke-width="1.5"/><path d="M67 30 L75 46 L59 46 Z" stroke="#1f2328" stroke-width="0.8" fill="none"/></svg>`, market()),
         tpl('Inertia', `<svg ${ATTRS} fill="none"><rect x="63" y="22" width="8" height="36" fill="#1f2328"/></svg>`, single(inertia())),
-        tpl('Link', `<svg ${ATTRS} fill="none"><path d="M24 40 H110" stroke="#666" stroke-width="2.4"/></svg>`, single(connect({ position: [0, 0] }, { position: [160, 0] }))),
-        tpl('Evolution arrow', `<svg ${ATTRS} fill="none"><path d="M24 40 H100" stroke="#d6455d" stroke-width="2.4" stroke-dasharray="6 4"/><path d="M98 33 L112 40 L98 47 Z" fill="#d6455d"/></svg>`, single(connect({ position: [0, 0] }, { position: [160, 0] }, { red: true }))),
+        // NEUTRAL on purpose (`docs/adr/0010` § Compatibility). This is a horizontal
+        // stroke bound to nothing — a sample of a STYLE, in a palette. It was typed
+        // `wardley:dependency` only because the helper defaults to that role, and a
+        // sample of a stroke makes no claim about who depends on whom. Same call the
+        // market glyph's own wiring already makes.
+        tpl('Link', `<svg ${ATTRS} fill="none"><path d="M24 40 H110" stroke="#666" stroke-width="2.4"/></svg>`, single(connect({ position: [0, 0] }, { position: [160, 0] }, { typed: false }))),
+        tpl('Evolution arrow', `<svg ${ATTRS} fill="none"><path d="M24 40 H100" stroke="#d6455d" stroke-width="2.4" stroke-dasharray="6 4"/><path d="M98 33 L112 40 L98 47 Z" fill="#d6455d"/></svg>`, single(connect({ position: [0, 0] }, { position: [160, 0] }, { evolution: true, typed: false }))),
     ],
 };

package/dist/templates/maps.js

@@ -1,6 +1,9 @@
 import { makeTemplateSnapshot, surfaceText, } from '@formicoidea/labre-core/gfx/template';
 import { ConnectorMode, FontFamily, PointStyle, ShapeStyle, StrokeStyle, TextAlign, } from '@formicoidea/labre-core/model';
-import { INERTIA_COLOR, LABEL_FONT_SIZE, LINK_GREY, LINK_STROKE_WIDTH, NODE_FILL, NODE_SIZE, NODE_STROKE, WARDLEY_RED, } from '../node/consts';
+import { INERTIA_COLOR, LABEL_FONT_SIZE, LINK_GREY, LINK_STROKE_WIDTH, NODE_FILL, NODE_SIZE, NODE_STROKE, WARDLEY_RED, } from '../node/consts.js';
+import { backgroundPlot, backgroundZoneBoundaries, } from '@formicoidea/labre-core/blocks/surface';
+import { WARDLEY_BACKGROUND } from '../background.js';
+import { WARDLEY_ROLE } from '../roles.js';
 /**
  * Authoring kit for canonical Wardley maps. Positions are given as
  * (evolution 0..1, value 0..1) and mapped into the plot interior of a fixed
@@ -11,19 +14,69 @@ import { INERTIA_COLOR, LABEL_FONT_SIZE, LINK_GREY, LINK_STROKE_WIDTH, NODE_FILL
  * arrow is the red dashed connector. Legends are produced by the editor's
  * auto-legend action rather than baked into the template.
  */
-const W = 1600;
-const H = 900;
-const PL = { x: 70, y: 56, w: 1470, h: 786 };
+const W = WARDLEY_BACKGROUND.geometry.width;
+const H = WARDLEY_BACKGROUND.geometry.height;
+/**
+ * The plot these templates lay their nodes out in — THE DECLARATION'S, read off
+ * `geometry.margin` rather than copied.
+ *
+ * It used to be a hand-written `{x:70, y:56, w:1470, h:786}`, inset further than
+ * the drawn plot (`x 40 → 1570, y 30 → 862`), with a comment calling the drift
+ * "harmless (everything lands inside the map) but not the same number".
+ *
+ * It stopped being harmless the moment a RULE measured against the plot. W2
+ * asks whether an inertia bar sits on a declared phase transition, and a
+ * transition is a ratio OF THE PLOT: two plots means an evolution of `0.7` in a
+ * template lands 25 units away from the `0.7` the background draws. The
+ * templates were laid out in one frame of reference and judged in another.
+ *
+ * Deriving it removes the possibility. The nodes of every preset move by a few
+ * units, which is a visual change to FACTORY CONTENT — acceptable, and the
+ * reason this could be fixed at the source rather than worked around: no user
+ * document is touched, because a template is data we ship, not data they wrote.
+ */
+const PLOT = backgroundPlot(WARDLEY_BACKGROUND, W, H);
+const PL = { x: PLOT.x0, y: PLOT.y0, w: PLOT.width, h: PLOT.height };
 const ex = (e) => PL.x + e * PL.w;
 const vy = (v) => PL.y + (1 - v) * PL.h;
 const D = NODE_SIZE; // 18
-const bg = (variant = 'classic') => ({ type: 'wardley', variant, xywh: `[0,0,${W},${H}]` });
+/** The evolution transitions, as plot ratios, straight from the declaration. */
+const PHASES = backgroundZoneBoundaries(WARDLEY_BACKGROUND).x;
+/**
+ * Where the segment `from → to` crosses the evolution transition at `PHASES[i]`,
+ * in (evolution, value) coordinates.
+ *
+ * This is where an inertia bar belongs: astride the boundary the thing refuses
+ * to cross — which is all W2 asks since the PO spelled it out (02/08/2026) — and
+ * on the dependency that would have to move, which the rule no longer demands
+ * and a well-drawn map still shows. Computed rather than eyeballed, so the
+ * symbol stays on both whatever the declaration says either of them is.
+ */
+function crossing(from, to, i) {
+    const at = PHASES[i];
+    const t = (at - from[0]) / (to[0] - from[0]);
+    return [at, from[1] + t * (to[1] - from[1])];
+}
+// The map carries `wardley:map`: rules position artefacts against the ROLE, so
+// a templated map is a first-class frame like a hand-drawn one — and since
+// PF13.4 every artefact these presets lay on it (nodes, labels, links, change
+// arrows, inertia bars) carries the same role the toolbox writes.
+const bg = (variant = 'classic') => ({
+    type: WARDLEY_BACKGROUND.type,
+    role: WARDLEY_BACKGROUND.role,
+    resizeEnabled: WARDLEY_BACKGROUND.geometry.resizable,
+    variant,
+    xywh: `[0,0,${W},${H}]`,
+});
 function dot(e, v, sw, stroke = NODE_STROKE, fill = NODE_FILL) {
     const cx = ex(e);
     const cy = vy(v);
     return {
         type: 'wardleyNode',
         kind: 'component',
+        // Templates carry the same semantic roles as the toolbox, so a map started
+        // from a preset validates exactly like a hand-drawn one.
+        role: WARDLEY_ROLE.component,
         shapeType: 'ellipse',
         filled: true,
         fillColor: fill,
@@ -43,6 +96,7 @@ function stake(e, v) {
     return {
         type: 'wardleyNode',
         kind: 'anchor',
+        role: WARDLEY_ROLE.anchor,
         shapeType: 'ellipse',
         filled: true,
         fillColor: NODE_FILL,
@@ -64,6 +118,10 @@ function lbl(e, v, text, o = {}) {
     return {
         type: 'text',
         text: surfaceText(text),
+        // The NAME of an artefact, so it carries the label role W3 is written on.
+        // The free texts these presets also use for notes and legends stay neutral:
+        // they name nothing and nothing measures them.
+        role: WARDLEY_ROLE.label,
         color: o.color ?? NODE_STROKE,
         fontFamily: FontFamily.Inter,
         fontSize: o.size ?? LABEL_FONT_SIZE,
@@ -71,15 +129,38 @@ function lbl(e, v, text, o = {}) {
         xywh: `[${x},${cy + dy},${w},26]`,
     };
 }
+/**
+ * A link between two nodes of a shipped map.
+ *
+ * `evolution` is the ONE predicate that decides what the stroke MEANS — the
+ * same flag `templates/index.ts` reads, aligned by `docs/adr/0010`
+ * § Compatibility. It used to be `arrow` here and `red` there, so a red SOLID
+ * Kodak link was a typed dependency while a red sample in the palette was not:
+ * two answers to "is this a dependency?" in one framework, in neighbouring
+ * files. Harmless as a style inconsistency, semantic the moment W4 reads these
+ * edges.
+ *
+ * `red` stays, and stays orthogonal: it colours a DEPENDENCY red (Kodak's
+ * future chain) without changing what it is. Colour is never what decides a
+ * relation's type.
+ *
+ * The direction is meaning, not decoration: `a` is the consumer, `b` is what it
+ * needs, and every one of the twelve links these presets ship respects it
+ * (a corpus test walks them and fails loudly the day one does not).
+ */
 function link(a, b, o = {}) {
     return {
         type: 'connector',
         mode: ConnectorMode.Straight,
-        stroke: o.red ? WARDLEY_RED : LINK_GREY,
-        strokeStyle: o.arrow ? StrokeStyle.Dash : StrokeStyle.Solid,
+        // An evolution arrow is a movement annotation, not a dependency — same
+        // split as the two Wardley connector tools, and since PF13.4 both sides of
+        // that split carry a role.
+        role: o.evolution ? WARDLEY_ROLE.changeArrow : WARDLEY_ROLE.dependency,
+        stroke: o.red || o.evolution ? WARDLEY_RED : LINK_GREY,
+        strokeStyle: o.evolution ? StrokeStyle.Dash : StrokeStyle.Solid,
         strokeWidth: LINK_STROKE_WIDTH,
         frontEndpointStyle: PointStyle.None,
-        rearEndpointStyle: o.arrow ? PointStyle.Triangle : PointStyle.None,
+        rearEndpointStyle: o.evolution ? PointStyle.Triangle : PointStyle.None,
         source: { id: a },
         target: { id: b },
     };
@@ -90,6 +171,7 @@ function inertia(e, v) {
     return {
         type: 'shape',
         shapeType: 'rect',
+        role: WARDLEY_ROLE.inertia,
         filled: true,
         fillColor: INERTIA_COLOR,
         strokeColor: INERTIA_COLOR,
@@ -199,7 +281,10 @@ function teaShop() {
         powerL: lbl(0.7, 0.1, 'Power', { align: 'right', dy: 6 }),
         powerFut: future(0.88, 0.1),
         powerFutL: lbl(0.88, 0.1, 'Power'),
-        limitedBy: lbl(0.56, 0.43, 'limited by', { align: 'center', w: 120, size: 13 }),
+        // ABOVE the link it annotates, not across it. Written on the line it reads
+        // as a label nobody can read — which is the finding W3 raises, and it was
+        // raising it on the map that ships as the canonical example.
+        limitedBy: lbl(0.56, 0.43, 'limited by', { align: 'center', w: 120, size: 13, dy: -34 }),
         ann1a: ann(0.5, 0.385), ann1t: annTxt(0.5, 0.385, '1'),
         ann2a: ann(0.84, 0.45), ann2t: annTxt(0.84, 0.45, '2'),
         l1: link('business', 'cupOfTea'),
@@ -210,34 +295,53 @@ function teaShop() {
         l6: link('hotWater', 'water'),
         l7: link('hotWater', 'kettle'),
         l8: link('kettle', 'power'),
-        a1: link('kettle', 'electric', { red: true, arrow: true }),
-        a2: link('power', 'powerFut', { red: true, arrow: true }),
+        a1: link('kettle', 'electric', { evolution: true }),
+        a2: link('power', 'powerFut', { evolution: true }),
     };
 }
 // ── Kodak inertia (2005) ──────────────────────────────────────────────
 function kodak() {
+    // The future dependency `capture → storage` is the movement Kodak resisted,
+    // and the inertia bar belongs where that dependency crosses into commodity —
+    // the boundary the capability refused to cross. It used to sit 105 units away
+    // from any transition: the template named after inertia was the
+    // counter-example to the inertia rule. Computed from the two node positions
+    // and the declared transitions, so it cannot drift again — and the bar comes
+    // out centred on the divider, which is exactly what W2 asks of it now that
+    // "astride the transition" is the whole of the rule.
+    const CAPTURE = [0.53, 0.8];
+    const STORAGE = [0.84, 0.4];
+    const [barE, barV] = crossing(CAPTURE, STORAGE, 2);
     return {
         bg: bg(),
         title: title("Wardley map of Kodak's 2005 inertia to digital"),
         user: stake(0.54, 0.92),
         userL: lbl(0.54, 0.92, 'User'),
-        capture: dot(0.53, 0.8, 3),
-        captureL: lbl(0.53, 0.8, 'Capture a moment'),
+        capture: dot(CAPTURE[0], CAPTURE[1], 3),
+        // To the LEFT, like the other two capability names: to the right of this
+        // node runs the future dependency towards digital storage, and a name
+        // written across the line that carries the whole argument is exactly the
+        // case W3 exists for.
+        captureL: lbl(CAPTURE[0], CAPTURE[1], 'Capture a moment', {
+            align: 'right',
+        }),
         film: comp(0.52, 0.62),
         filmL: lbl(0.52, 0.62, 'Film camera', { align: 'right' }),
         digital: future(0.74, 0.62),
         digitalL: lbl(0.74, 0.62, 'Digital camera', { color: WARDLEY_RED }),
         roll: comp(0.52, 0.4),
         rollL: lbl(0.52, 0.4, 'Photographic film', { align: 'right' }),
-        storage: future(0.84, 0.4),
-        storageL: lbl(0.84, 0.4, 'Digital storage', { color: WARDLEY_RED }),
-        inertiaBar: inertia(0.78, 0.4),
+        storage: future(STORAGE[0], STORAGE[1]),
+        storageL: lbl(STORAGE[0], STORAGE[1], 'Digital storage', {
+            color: WARDLEY_RED,
+        }),
+        inertiaBar: inertia(barE, barV),
         l1: link('user', 'capture'),
         l2: link('capture', 'film'),
         l3: link('film', 'roll'),
         r1: link('capture', 'storage', { red: true }),
-        a1: link('film', 'digital', { red: true, arrow: true }),
-        a2: link('roll', 'storage', { red: true, arrow: true }),
+        a1: link('film', 'digital', { evolution: true }),
+        a2: link('roll', 'storage', { evolution: true }),
     };
 }
 export const wardleyMaps = [

package/dist/toolbar/config.js

@@ -3,8 +3,8 @@ import { WardleyBackgroundElementModel } from '@formicoidea/labre-core/model';
 import { TelemetryProvider, ToolbarModuleExtension, } from '@formicoidea/labre-core/shared/services';
 import { BlockFlavourIdentifier } from '@formicoidea/labre-core/std';
 import { html } from 'lit';
-import { createWardleyLegend } from '../legend';
-import { wardleyLegendIcon } from './icons';
+import { createWardleyLegend } from '../legend.js';
+import { wardleyLegendIcon } from './icons.js';
 const ResizeIcon = html `<svg
   width="24"
   height="24"