@formicoidea/labre-framework-wardley 0.30.1 → 0.32.0

package/dist/element-renderer.js

@@ -1,150 +1,15 @@
-import { ElementRendererExtension, } from '@formicoidea/labre-core/blocks/surface';
-import { ARROW, CARD_RADIUS, COLORS, EVOLUTION_BOUNDARIES, FONT_FAMILY, FONTS, LINE, MARGIN, OFFSETS, } from './consts';
-import { paintGradientBackground } from './gradient';
-function roundRectPath(ctx, x, y, w, h, r) {
-    const rr = Math.min(r, w / 2, h / 2);
-    ctx.beginPath();
-    ctx.moveTo(x + rr, y);
-    ctx.arcTo(x + w, y, x + w, y + h, rr);
-    ctx.arcTo(x + w, y + h, x, y + h, rr);
-    ctx.arcTo(x, y + h, x, y, rr);
-    ctx.arcTo(x, y, x + w, y, rr);
-    ctx.closePath();
-}
+import { createFrameworkBackgroundRenderer, ElementRendererExtension, } from '@formicoidea/labre-core/blocks/surface';
+import { WARDLEY_BACKGROUND } from './background.js';
 /**
- * Canvas renderer for the Wardley map background — reproduces mockup C:
- * an L-shaped axes frame (no top/right border), dashed evolution dividers and
- * the symmetric axis labels.
+ * Canvas renderer for the Wardley map background.
  *
- * All sizes (fonts, margins, offsets, strokes) are FIXED model units — they do
- * not scale with the element size. Only the plot interior scales.
+ * There is no Wardley drawing code any more (PF2.12): the map is an
+ * INSTANTIATION of the framework-background primitive, configured by the
+ * `WARDLEY_BACKGROUND` declaration. What used to be two hundred lines of
+ * `ctx.fillText` is now a declaration any other framework can write for itself.
+ *
+ * Exported as a function as well as an extension because the non-regression
+ * suite drives it directly with a canvas stub.
  */
-export const wardley = (model, ctx, matrix) => {
-    const [, , w, h] = model.deserializedXYWH;
-    const cx = w / 2;
-    const cy = h / 2;
-    ctx.setTransform(matrix.translateSelf(cx, cy).rotateSelf(model.rotate).translateSelf(-cx, -cy));
-    const px0 = MARGIN.left;
-    const px1 = w - MARGIN.right;
-    const py0 = MARGIN.top;
-    const py1 = h - MARGIN.bottom;
-    const pw = px1 - px0;
-    const ph = py1 - py0;
-    const ex = (r) => px0 + r * pw;
-    const line = (x1, y1, x2, y2) => {
-        ctx.beginPath();
-        ctx.moveTo(x1, y1);
-        ctx.lineTo(x2, y2);
-        ctx.stroke();
-    };
-    const vtext = (text, x, y, fontSize, color) => {
-        ctx.save();
-        ctx.translate(x, y);
-        ctx.rotate(-Math.PI / 2);
-        ctx.font = `${fontSize}px ${FONT_FAMILY}`;
-        ctx.fillStyle = color;
-        ctx.textAlign = 'center';
-        ctx.textBaseline = 'alphabetic';
-        ctx.fillText(text, 0, 0);
-        ctx.restore();
-    };
-    // ── Card (element bounds) ───────────────────────────────────────────
-    const inset = LINE.card / 2;
-    roundRectPath(ctx, inset, inset, w - inset * 2, h - inset * 2, CARD_RADIUS);
-    ctx.fillStyle = COLORS.card;
-    ctx.fill();
-    ctx.strokeStyle = COLORS.cardBorder;
-    ctx.lineWidth = LINE.card;
-    ctx.stroke();
-    // ── Curve-driven gradient variants (inscribed in the frame) ─────────
-    // Hidden when `showGradient` is false → plain white background.
-    if (model.variant !== 'classic' && model.showGradient) {
-        paintGradientBackground(ctx, model.variant, px0, px1, py0, py1);
-    }
-    // ── Optional evolution band tints ───────────────────────────────────
-    if (model.banded) {
-        const starts = [0, 0.175, 0.4, 0.7];
-        const ends = [0.175, 0.4, 0.7, 1];
-        for (let i = 0; i < 4; i++) {
-            ctx.fillStyle = COLORS.band[i];
-            ctx.fillRect(ex(starts[i]), py0, ex(ends[i]) - ex(starts[i]), ph);
-        }
-    }
-    // ── Evolution phase dividers (dashed) ───────────────────────────────
-    if (model.showColumnDividers) {
-        ctx.strokeStyle = COLORS.divider;
-        ctx.lineWidth = LINE.divider;
-        ctx.setLineDash([5, 5]);
-        for (const r of EVOLUTION_BOUNDARIES) {
-            line(ex(r), py0, ex(r), py1);
-        }
-        ctx.setLineDash([]);
-    }
-    // ── Axes (L shape) + arrowheads ─────────────────────────────────────
-    // X and Y axes are independently toggleable. Each line stops at the base of
-    // its arrowhead (1px overlap, hidden under the triangle) so the line never
-    // pokes past the tip on zoom.
-    ctx.strokeStyle = COLORS.axis;
-    ctx.lineWidth = LINE.axis;
-    ctx.fillStyle = COLORS.axis;
-    if (model.showXAxis) {
-        line(px0, py1, px1 - ARROW + 1, py1); // X axis (arrow tip at px1)
-        ctx.beginPath(); // X arrow (points right)
-        ctx.moveTo(px1, py1);
-        ctx.lineTo(px1 - ARROW, py1 - ARROW / 2);
-        ctx.lineTo(px1 - ARROW, py1 + ARROW / 2);
-        ctx.closePath();
-        ctx.fill();
-    }
-    if (model.showYAxis) {
-        line(px0, py1, px0, py0 + ARROW - 1); // Y axis (arrow tip at py0)
-        ctx.beginPath(); // Y arrow (points up)
-        ctx.moveTo(px0, py0);
-        ctx.lineTo(px0 - ARROW / 2, py0 + ARROW);
-        ctx.lineTo(px0 + ARROW / 2, py0 + ARROW);
-        ctx.closePath();
-        ctx.fill();
-    }
-    // ── Horizontal labels ───────────────────────────────────────────────
-    ctx.textBaseline = 'alphabetic';
-    // Phase (column) labels (left-aligned at each zone start)
-    if (model.showColumnLabels) {
-        ctx.font = `${FONTS.phase}px ${FONT_FAMILY}`;
-        ctx.fillStyle = COLORS.label;
-        ctx.textAlign = 'left';
-        const phases = [
-            [model.phase0, 0],
-            [model.phase1, 0.175],
-            [model.phase2, 0.4],
-            [model.phase3, 0.7],
-        ];
-        for (const [label, start] of phases) {
-            ctx.fillText(label, ex(start) + OFFSETS.phasePad, py1 + OFFSETS.phaseBaseline);
-        }
-    }
-    // "Evolution" title near the X arrow (tied to the X axis)
-    if (model.showXAxis) {
-        ctx.font = `${FONTS.axis}px ${FONT_FAMILY}`;
-        ctx.fillStyle = COLORS.axis;
-        ctx.textAlign = 'right';
-        ctx.fillText(model.xAxisTitle, px1 - OFFSETS.evolutionPadRight, py1 + OFFSETS.phaseBaseline);
-    }
-    // Direction indicators (Uncharted / Industrialized, top corners)
-    if (model.showCornerLabels) {
-        ctx.font = `${FONTS.direction}px ${FONT_FAMILY}`;
-        ctx.fillStyle = COLORS.label;
-        ctx.textAlign = 'left';
-        ctx.fillText(model.evolutionStart, px0 + OFFSETS.directionPadLeft, py0 + OFFSETS.directionTop);
-        ctx.textAlign = 'right';
-        ctx.fillText(model.evolutionEnd, px1 - OFFSETS.directionPadRight, py0 + OFFSETS.directionTop);
-    }
-    // ── Rotated Y labels (hugging the axis, symmetric with the X labels) ─
-    if (model.showYAxis) {
-        vtext(model.yAxisTitle, px0 - OFFSETS.yHug, (py0 + py1) / 2, FONTS.axis, COLORS.axis);
-    }
-    if (model.showVisibilityLabels) {
-        vtext(model.visibilityHigh, px0 - OFFSETS.yHug, py0 + OFFSETS.visibleTop, FONTS.visibility, COLORS.label);
-        vtext(model.visibilityLow, px0 - OFFSETS.yHug, py1 - OFFSETS.invisibleBottom, FONTS.visibility, COLORS.label);
-    }
-};
-export const WardleyElementRendererExtension = ElementRendererExtension('wardley', wardley);
+export const wardley = createFrameworkBackgroundRenderer(WARDLEY_BACKGROUND);
+export const WardleyElementRendererExtension = ElementRendererExtension(WARDLEY_BACKGROUND.type, wardley);

package/dist/element-view.d.ts

@@ -8,13 +8,17 @@ export declare class WardleyView extends GfxElementModelView<WardleyBackgroundEl
     onDestroyed(): void;
     /** 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".
+     */
     private _openLabelEditor;
     private _closeLabelEditor;
 }
 /**
- * Resize gating: the resize handles are hidden unless `model.resizeEnabled` is
- * true. `beforeResize` is re-evaluated every time the allowed handles are
- * computed (manager.ts), so toggling the field from the toolbar updates the
- * handles reactively. Moving/selecting stays available throughout.
+ * Resize gating, from the primitive: the handles stay hidden until
+ * `resizeEnabled` is true — the runtime half of the declaration's
+ * `geometry.resizable`.
  */
 export declare const WardleyInteraction: import("@formicoidea/labre-core/store").ExtensionType;

package/dist/element-view.js

@@ -1,7 +1,8 @@
-import { EdgelessCRUDIdentifier } from '@formicoidea/labre-core/blocks/surface';
+import { backgroundLabelHits, EdgelessCRUDIdentifier, FrameworkBackgroundInteractionExtension, hitTestBackgroundLabel, } from '@formicoidea/labre-core/blocks/surface';
+import { TranslationProvider } from '@formicoidea/labre-core/shared/services';
 import { rotatePoint } from '@formicoidea/labre-core/global/gfx';
-import { GfxElementModelView, GfxViewInteractionExtension, } from '@formicoidea/labre-core/std/gfx';
-import { getWardleyLabelHits, hitTestWardleyLabel, } from './label-layout';
+import { GfxElementModelView } from '@formicoidea/labre-core/std/gfx';
+import { isWardleyLabelProp, WARDLEY_BACKGROUND, } from './background.js';
 export class WardleyView extends GfxElementModelView {
     constructor() {
         super(...arguments);
@@ -34,15 +35,27 @@ export class WardleyView extends GfxElementModelView {
             lx = ux - bx;
             ly = uy - by;
         }
-        const hit = hitTestWardleyLabel(getWardleyLabelHits(this.model, w, h), lx, ly);
+        // 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.
+        const hit = hitTestBackgroundLabel(backgroundLabelHits(WARDLEY_BACKGROUND, this.model, w, h, this.gfx.std.getOptional(TranslationProvider)), lx, ly);
         if (!hit)
             return;
-        this._openLabelEditor(hit.field, e);
+        // The declaration names the prop; this decides whether it may be written.
+        if (!isWardleyLabelProp(hit.prop))
+            return;
+        this._openLabelEditor(hit.prop, hit.text, e);
     }
-    _openLabelEditor(field, e) {
+    /**
+     * @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".
+     */
+    _openLabelEditor(field, current, e) {
         this._closeLabelEditor();
         const input = document.createElement('input');
-        input.value = String(this.model[field] ?? '');
+        input.value = current;
         Object.assign(input.style, {
             position: 'fixed',
             left: `${e.raw.clientX}px`,
@@ -73,6 +86,12 @@ export class WardleyView extends GfxElementModelView {
                 return;
             const value = input.value;
             this._closeLabelEditor();
+            // Opening an editor is not renaming. Writing back an untouched value
+            // would persist the resolved VOCABULARY as the user's own text, freezing
+            // the label in whatever language it was read in and putting it beyond
+            // any catalogue for good — and it would push an empty entry onto undo.
+            if (value === current)
+                return;
             this.gfx.std.store.captureSync();
             this.gfx.std
                 .get(EdgelessCRUDIdentifier)
@@ -103,19 +122,8 @@ export class WardleyView extends GfxElementModelView {
     }
 }
 /**
- * Resize gating: the resize handles are hidden unless `model.resizeEnabled` is
- * true. `beforeResize` is re-evaluated every time the allowed handles are
- * computed (manager.ts), so toggling the field from the toolbar updates the
- * handles reactively. Moving/selecting stays available throughout.
+ * Resize gating, from the primitive: the handles stay hidden until
+ * `resizeEnabled` is true — the runtime half of the declaration's
+ * `geometry.resizable`.
  */
-export const WardleyInteraction = GfxViewInteractionExtension(WardleyView.type, {
-    handleResize({ model }) {
-        return {
-            beforeResize({ set }) {
-                if (!model.resizeEnabled) {
-                    set({ allowedHandlers: [] });
-                }
-            },
-        };
-    },
-});
+export const WardleyInteraction = FrameworkBackgroundInteractionExtension(WARDLEY_BACKGROUND);

package/dist/gradient.d.ts

@@ -1,15 +1,10 @@
-/**
- * Curve-driven gradient backgrounds (Slice C). Each analytic background is a
- * smooth mathematical curve (piecewise asymmetric Gaussian bells); the gradient
- * opacity at each evolution position X follows that curve, normalised between
- * its own min and max — i.e. the gradient is strongest where the curve peaks and
- * fades to nothing at its minimum. Validated against the reference images at
- * `../wardley-mockups/gradient-backgrounds.html`.
- */
+import type { BackgroundWashDef } from '@formicoidea/labre-core/blocks/surface';
 export declare const GRADIENT_GREEN = "#1f9e4d";
 export declare const GRADIENT_RED = "#d6455d";
 /**
- * Paint the curve-driven gradient over the plot rectangle [px0,px1]×[py0,py1]
- * in element-local coordinates. `classic` paints nothing.
+ * The washes the Wardley declaration ships, in painting order. Only those whose
+ * `variants` name the background's current `variant` are painted, and only
+ * while `showGradient` is on — so `classic` paints none of them and the frame
+ * stays plain white, exactly as before.
  */
-export declare function paintGradientBackground(ctx: CanvasRenderingContext2D, variant: 'opportunity' | 'benefit' | 'evolution-gradient', px0: number, px1: number, py0: number, py1: number): void;
+export declare const WARDLEY_WASHES: readonly BackgroundWashDef[];

package/dist/gradient.js

@@ -5,6 +5,11 @@
  * its own min and max — i.e. the gradient is strongest where the curve peaks and
  * fades to nothing at its minimum. Validated against the reference images at
  * `../wardley-mockups/gradient-backgrounds.html`.
+ *
+ * The curves are TABULATED ONCE, here, at module load: what the declaration
+ * ships — and what the primitive paints — is a table of `[offset, alpha]`
+ * stops, not a function. Nothing is evaluated at paint time, and the wash is
+ * data like the rest of the declaration (PF2.1).
  */
 const bell = (x, mu, s) => Math.exp(-0.5 * ((x - mu) / s) ** 2);
 const asym = (x, mu, sL, sR) => Math.exp(-0.5 * ((x - mu) / (x < mu ? sL : sR)) ** 2);
@@ -48,62 +53,68 @@ const GRADIENT_GREY = '#7c8389';
 const GRADIENT_MAX_OPACITY = 0.45;
 /** Peak opacity for the grey evolution-gradient variant. */
 const GREY_MAX_OPACITY = 0.38;
-function rgba(hex, alpha) {
-    const r = parseInt(hex.slice(1, 3), 16);
-    const g = parseInt(hex.slice(3, 5), 16);
-    const b = parseInt(hex.slice(5, 7), 16);
-    return `rgba(${r},${g},${b},${alpha})`;
-}
 /**
- * Add stops to a horizontal gradient (offset 0..1 spanning the plot width) for
- * a function-driven opacity profile within [x0, x1] (zero outside).
+ * Tabulate one opacity profile as gradient stops spanning the plot width:
+ * 49 samples inside [x0, x1], bracketed by a zero stop wherever the profile
+ * does not reach the edge of the plot.
  */
-function addStops(grad, hex, opacityFn, x0, x1, maxOp = GRADIENT_MAX_OPACITY) {
+function stopTable(opacityFn, x0, x1, maxOp = GRADIENT_MAX_OPACITY) {
     const eps = 0.001;
+    const stops = [];
     if (x0 > eps)
-        grad.addColorStop(Math.max(0, x0 - eps), rgba(hex, 0));
+        stops.push([Math.max(0, x0 - eps), 0]);
     const N = 48;
     for (let i = 0; i <= N; i++) {
         const x = x0 + ((x1 - x0) * i) / N;
-        grad.addColorStop(clamp01(x), rgba(hex, clamp01(opacityFn(x)) * maxOp));
+        stops.push([clamp01(x), clamp01(opacityFn(x)) * maxOp]);
     }
     if (x1 < 1 - eps)
-        grad.addColorStop(Math.min(1, x1 + eps), rgba(hex, 0));
+        stops.push([Math.min(1, x1 + eps), 0]);
+    return stops;
 }
+// benefit: green where the curve is positive, red where negative.
+const BEN_MAX_POS = RB.hi;
+const BEN_MAX_NEG = -RB.lo;
 /**
- * Paint the curve-driven gradient over the plot rectangle [px0,px1]×[py0,py1]
- * in element-local coordinates. `classic` paints nothing.
+ * The washes the Wardley declaration ships, in painting order. Only those whose
+ * `variants` name the background's current `variant` are painted, and only
+ * while `showGradient` is on — so `classic` paints none of them and the frame
+ * stays plain white, exactly as before.
  */
-export function paintGradientBackground(ctx, variant, px0, px1, py0, py1) {
-    const w = px1 - px0;
-    const h = py1 - py0;
-    if (variant === 'evolution-gradient') {
-        const grey = ctx.createLinearGradient(px0, 0, px1, 0);
-        addStops(grey, GRADIENT_GREY, fGrey, 0, 1, GREY_MAX_OPACITY);
-        ctx.fillStyle = grey;
-        ctx.fillRect(px0, py0, w, h);
-        return;
-    }
-    if (variant === 'opportunity') {
-        const green = ctx.createLinearGradient(px0, 0, px1, 0);
-        addStops(green, GRADIENT_GREEN, x => norm(fDiff(x), RG.lo, RG.hi), DIFF_DOM[0], DIFF_DOM[1]);
-        ctx.fillStyle = green;
-        ctx.fillRect(px0, py0, w, h);
-        const red = ctx.createLinearGradient(px0, 0, px1, 0);
-        addStops(red, GRADIENT_RED, x => norm(fOper(x), RR.lo, RR.hi), OPER_DOM[0], OPER_DOM[1]);
-        ctx.fillStyle = red;
-        ctx.fillRect(px0, py0, w, h);
-        return;
-    }
-    // benefit: green where the curve is positive, red where negative.
-    const maxPos = RB.hi;
-    const maxNeg = -RB.lo;
-    const green = ctx.createLinearGradient(px0, 0, px1, 0);
-    addStops(green, GRADIENT_GREEN, x => Math.max(0, fBen(x)) / maxPos, 0, 1);
-    ctx.fillStyle = green;
-    ctx.fillRect(px0, py0, w, h);
-    const red = ctx.createLinearGradient(px0, 0, px1, 0);
-    addStops(red, GRADIENT_RED, x => Math.max(0, -fBen(x)) / maxNeg, 0, 1);
-    ctx.fillStyle = red;
-    ctx.fillRect(px0, py0, w, h);
-}
+export const WARDLEY_WASHES = [
+    {
+        id: 'evolution-grey',
+        variants: ['evolution-gradient'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_GREY,
+        stops: stopTable(fGrey, 0, 1, GREY_MAX_OPACITY),
+    },
+    {
+        id: 'opportunity-differential',
+        variants: ['opportunity'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_GREEN,
+        stops: stopTable(x => norm(fDiff(x), RG.lo, RG.hi), DIFF_DOM[0], DIFF_DOM[1]),
+    },
+    {
+        id: 'opportunity-operational',
+        variants: ['opportunity'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_RED,
+        stops: stopTable(x => norm(fOper(x), RR.lo, RR.hi), OPER_DOM[0], OPER_DOM[1]),
+    },
+    {
+        id: 'benefit-positive',
+        variants: ['benefit'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_GREEN,
+        stops: stopTable(x => Math.max(0, fBen(x)) / BEN_MAX_POS, 0, 1),
+    },
+    {
+        id: 'benefit-investment',
+        variants: ['benefit'],
+        visibleProp: 'showGradient',
+        color: GRADIENT_RED,
+        stops: stopTable(x => Math.max(0, -fBen(x)) / BEN_MAX_NEG, 0, 1),
+    },
+];

package/dist/index.d.ts

@@ -1 +1,9 @@
-export { wardleyShortcuts } from './shortcuts';
+export { WARDLEY_ROLE, WARDLEY_ROLES, type WardleyRole, type WardleyRoleId, } from './roles.js';
+export { WARDLEY_AUDIT_CRITERIA } from './audit-criteria.js';
+export { wardleyCommandIcons, wardleyCommands } from './commands.js';
+export { wardleyTranslationEntries } from './translations.js';
+export { WARDLEY_NATURE, WARDLEY_NATURE_TAG_ID, WARDLEY_TAG_DEFS, } from './natures.js';
+export { WARDLEY_PROFILES } from './profiles.js';
+export { WARDLEY_NUDGES } from './nudges.js';
+export { WARDLEY_NAMING_CONVENTIONS, WARDLEY_READING } from './reading.js';
+export { WARDLEY_RULES } from './rules.js';

package/dist/index.js

@@ -1 +1,9 @@
-export { wardleyShortcuts } from './shortcuts';
+export { WARDLEY_ROLE, WARDLEY_ROLES, } from './roles.js';
+export { WARDLEY_AUDIT_CRITERIA } from './audit-criteria.js';
+export { wardleyCommandIcons, wardleyCommands } from './commands.js';
+export { wardleyTranslationEntries } from './translations.js';
+export { WARDLEY_NATURE, WARDLEY_NATURE_TAG_ID, WARDLEY_TAG_DEFS, } from './natures.js';
+export { WARDLEY_PROFILES } from './profiles.js';
+export { WARDLEY_NUDGES } from './nudges.js';
+export { WARDLEY_NAMING_CONVENTIONS, WARDLEY_READING } from './reading.js';
+export { WARDLEY_RULES } from './rules.js';

package/dist/legend.js

@@ -2,8 +2,8 @@ import { createGroupCommand } from '@formicoidea/labre-core/gfx/group';
 import { ConnectorElementModel, ConnectorMode, FontFamily, PointStyle, ShapeElementModel, ShapeStyle, StrokeStyle, WardleyNodeElementModel, } from '@formicoidea/labre-core/model';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
 import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
-import { GRADIENT_GREEN, GRADIENT_RED } from './gradient';
-import { INERTIA_COLOR, LINK_GREY, LINK_STROKE_WIDTH, MARKET_DOT_STROKE_WIDTH, MARKET_LINK_COLOR, MARKET_LINK_WIDTH, METHOD_FILL, NODE_FILL, NODE_STROKE, NODE_STROKE_WIDTH, PIPELINE_FILL, WARDLEY_RED, } from './node/consts';
+import { GRADIENT_GREEN, GRADIENT_RED } from './gradient.js';
+import { INERTIA_COLOR, LINK_GREY, LINK_STROKE_WIDTH, MARKET_DOT_STROKE_WIDTH, MARKET_LINK_COLOR, MARKET_LINK_WIDTH, METHOD_FILL, NODE_FILL, NODE_STROKE, NODE_STROKE_WIDTH, PIPELINE_FILL, WARDLEY_RED, } from './node/consts.js';
 const LEGEND_ORDER = [
     'component',
     'anchor',
@@ -110,6 +110,14 @@ export function createWardleyLegend(std, bg) {
         xywh: new Bound(x, y, w, h).serialize(),
     });
     // ── glyph builders (real, editable elements), centred on (cx, cy) ─────
+    //
+    // DELIBERATELY ROLE-LESS. These are real `wardleyNode` elements, but a
+    // legend documents the map — it is not part of it. Giving its glyphs
+    // `wardley:component` & co. would make every legend entry count as an
+    // artefact and skew any rule written against roles (a legend would add a
+    // phantom component, anchor, market…). Neutral is the semantics we want;
+    // `kind` still drives their rendering. Frozen by a test in
+    // `__tests__/roles.unit.spec.ts`.
     const ellipse = (kind, d, fill, sw, cx, cy) => surface.addElement({
         type: 'wardleyNode',
         kind,

package/dist/natures.d.ts

@@ -0,0 +1,50 @@
+import type { UniverseTagDefs } from '@formicoidea/labre-core/shared/services';
+/**
+ * The Wardley **nature** tag — the framework's type-3 contextual qualification
+ * (PRD level 3, ADR 0007).
+ *
+ * A component's nature answers "what KIND of thing is this?", which is a
+ * different question from its role ("what is it, on a map?") and from its
+ * position ("how evolved is it?"). Simon Wardley's four are activity, data,
+ * practice and knowledge, and mapping practitioners routinely draw all four on
+ * one map — the same circle, the same axes, four different things.
+ *
+ * ## Why this ships as DATA, on the host's own mechanism
+ *
+ * The library fixes the FORMAT of tag definitions; the application seeds them.
+ * Nothing here is privileged: this pack is registered through the same
+ * `UniverseTagDefsExtension` a host uses for its own taxonomy, and a client's
+ * private extension of Wardley — say a `criticality` tag — is a second pack
+ * with a different `packId` that merges with this one, with no library release.
+ * Shipping one real pack is what keeps that mechanism honest.
+ *
+ * ## Why it applies to `wardley:component` and not to `'*'`
+ *
+ * A nature qualifies a component. `market` and `ecosystem` specialise
+ * `wardley:component`, so they get it for free through `roleIsA` — that is the
+ * entire reason role hierarchy is data. The `anchor` (a user / need) is
+ * deliberately NOT a child of `component` and is deliberately NOT qualified
+ * here: a need has no nature, it has a demand. The map itself, the change
+ * arrow, the inertia bar and the labels are chrome or annotations and are not
+ * candidates either.
+ *
+ * ## Why `cardinality: 'single'`
+ *
+ * A component is one of the four, not several. Where practitioners disagree —
+ * "is a data pipeline data or an activity?" — the disagreement is the finding,
+ * and forcing one answer is what makes the finding visible. A multi-valued
+ * nature would let the ambiguity hide inside the element.
+ *
+ * Labels are English fallbacks: the host localizes them. The library never
+ * pretends a def's `label` is already translated for someone else's locale, and
+ * a pack shipped as a `.json` asset carries whatever the host put in it.
+ */
+export declare const WARDLEY_NATURE_TAG_ID = "wardley:nature";
+/** The four natures, as value ids. Ids are forever; a def is only deprecated. */
+export declare const WARDLEY_NATURE: {
+    readonly activity: "wardley:nature/activity";
+    readonly data: "wardley:nature/data";
+    readonly practice: "wardley:nature/practice";
+    readonly knowledge: "wardley:nature/knowledge";
+};
+export declare const WARDLEY_TAG_DEFS: UniverseTagDefs;

package/dist/natures.js

@@ -0,0 +1,93 @@
+import { WARDLEY_ROLE } from './roles.js';
+/**
+ * The Wardley **nature** tag — the framework's type-3 contextual qualification
+ * (PRD level 3, ADR 0007).
+ *
+ * A component's nature answers "what KIND of thing is this?", which is a
+ * different question from its role ("what is it, on a map?") and from its
+ * position ("how evolved is it?"). Simon Wardley's four are activity, data,
+ * practice and knowledge, and mapping practitioners routinely draw all four on
+ * one map — the same circle, the same axes, four different things.
+ *
+ * ## Why this ships as DATA, on the host's own mechanism
+ *
+ * The library fixes the FORMAT of tag definitions; the application seeds them.
+ * Nothing here is privileged: this pack is registered through the same
+ * `UniverseTagDefsExtension` a host uses for its own taxonomy, and a client's
+ * private extension of Wardley — say a `criticality` tag — is a second pack
+ * with a different `packId` that merges with this one, with no library release.
+ * Shipping one real pack is what keeps that mechanism honest.
+ *
+ * ## Why it applies to `wardley:component` and not to `'*'`
+ *
+ * A nature qualifies a component. `market` and `ecosystem` specialise
+ * `wardley:component`, so they get it for free through `roleIsA` — that is the
+ * entire reason role hierarchy is data. The `anchor` (a user / need) is
+ * deliberately NOT a child of `component` and is deliberately NOT qualified
+ * here: a need has no nature, it has a demand. The map itself, the change
+ * arrow, the inertia bar and the labels are chrome or annotations and are not
+ * candidates either.
+ *
+ * ## Why `cardinality: 'single'`
+ *
+ * A component is one of the four, not several. Where practitioners disagree —
+ * "is a data pipeline data or an activity?" — the disagreement is the finding,
+ * and forcing one answer is what makes the finding visible. A multi-valued
+ * nature would let the ambiguity hide inside the element.
+ *
+ * Labels are English fallbacks: the host localizes them. The library never
+ * pretends a def's `label` is already translated for someone else's locale, and
+ * a pack shipped as a `.json` asset carries whatever the host put in it.
+ */
+export const WARDLEY_NATURE_TAG_ID = 'wardley:nature';
+/** The four natures, as value ids. Ids are forever; a def is only deprecated. */
+export const WARDLEY_NATURE = {
+    activity: `${WARDLEY_NATURE_TAG_ID}/activity`,
+    data: `${WARDLEY_NATURE_TAG_ID}/data`,
+    practice: `${WARDLEY_NATURE_TAG_ID}/practice`,
+    knowledge: `${WARDLEY_NATURE_TAG_ID}/knowledge`,
+};
+export const WARDLEY_TAG_DEFS = {
+    formatVersion: 1,
+    // The id of this PACK, not of the framework: several packs may extend
+    // Wardley, and re-registering this one replaces it rather than duplicating
+    // it.
+    packId: 'wardley-core',
+    framework: 'wardley',
+    label: 'Wardley',
+    tags: [
+        {
+            id: WARDLEY_NATURE_TAG_ID,
+            label: 'Nature',
+            description: 'What kind of thing this component is: an activity, data, a practice or knowledge.',
+            cardinality: 'single',
+            appliesTo: [WARDLEY_ROLE.component],
+            // No `order`: it is the only tag this pack declares, and an absent order
+            // sorts by SEED order, which is what puts the library's pack ahead of a
+            // client's extension without either having to know about the other. A
+            // number here would be a claim about packs that do not exist yet.
+            values: [
+                {
+                    id: WARDLEY_NATURE.activity,
+                    label: 'Activity',
+                    description: 'Something that is DONE — a step, a service, a process.',
+                },
+                {
+                    id: WARDLEY_NATURE.data,
+                    label: 'Data',
+                    description: 'Something that is RECORDED — a dataset, a register.',
+                },
+                {
+                    id: WARDLEY_NATURE.practice,
+                    label: 'Practice',
+                    description: 'A way of doing — a method, a convention, an operating model.',
+                },
+                {
+                    id: WARDLEY_NATURE.knowledge,
+                    label: 'Knowledge',
+                    description: 'Something that is KNOWN — a model, a theory, a rule.',
+                },
+            ],
+        },
+    ],
+};

package/dist/node/node-renderer.js

@@ -1,7 +1,7 @@
 import { ElementRendererExtension, } from '@formicoidea/labre-core/blocks/surface';
 import { shape as shapeRenderer } from '@formicoidea/labre-core/gfx/shape';
 import { DefaultTheme } from '@formicoidea/labre-core/model';
-import { ANCHOR, ECOSYSTEM, METHOD, NODE_FILL } from './consts';
+import { ANCHOR, ECOSYSTEM, METHOD, NODE_FILL } from './consts.js';
 /**
  * Renderer for a Wardley node. The circle is drawn by REUSING the native shape
  * renderer (so stroke width, colors and theme behave exactly like a native