@formicoidea/labre-framework-cynefin 0.37.0 → 0.38.1

package/dist/actions.js

@@ -1,73 +1,48 @@
 import { DefaultTool } from '@formicoidea/labre-core/blocks/surface';
-import { ShapeStyle, TextFitMode } from '@formicoidea/labre-core/model';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
 import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
-import { REF_H as CYN_H, REF_W as CYN_W } from './cynefin/consts.js';
-import { HEX_FILL, HEX_SIZE, HEX_STROKE, HEX_VERTICES, REF_H as EST_H, REF_W as EST_W, } from './estuarine/consts.js';
-import { ESTUARINE_ROLE } from './estuarine/roles.js';
+import { CYNEFIN_H, CYNEFIN_W, cynefinBackgroundProps, ESTUARINE_MAP_H, ESTUARINE_MAP_W, estuarineHexagonBox, estuarineHexagonProps, estuarineMapProps, } from './presets.js';
 /**
  * Creation actions for the Cynefin / Estuarine toolbox — lifted out of
  * `toolbar/menu.ts` by PF3. This is also the framework that emitted NO
  * telemetry at all before the switchover: routing every surface through
  * `runCommand` fixes that for free (`docs/adr/0008`).
+ *
+ * What each artefact IS lives in `presets.ts`, which the palette reads too: the
+ * templates used to restate these props and drifted from them.
  */
-/** Estuarine map default size (REF aspect, scaled up so it reads on canvas). */
-const MAP_SCALE = 1.2;
 const gfxOf = (std) => std.get(GfxControllerIdentifier);
 function finish(gfx, id) {
     gfx.doc.captureSync();
     gfx.tool.setTool(DefaultTool);
     gfx.selection.set({ elements: [id], editing: false });
 }
+/** The box an artefact of the given size is born in, centred on the viewport. */
+function centered(gfx, width, height) {
+    const { centerX, centerY } = gfx.viewport;
+    return new Bound(centerX - width / 2, centerY - height / 2, width, height).serialize();
+}
 export function createCynefin(std) {
     const gfx = gfxOf(std);
     if (!gfx.surface)
         return;
-    const { centerX, centerY } = gfx.viewport;
-    const id = gfx.surface.addElement({
-        type: 'cynefin',
-        xywh: new Bound(centerX - CYN_W / 2, centerY - CYN_H / 2, CYN_W, CYN_H).serialize(),
-    });
+    const id = gfx.surface.addElement(cynefinBackgroundProps({ xywh: centered(gfx, CYNEFIN_W, CYNEFIN_H) }));
     finish(gfx, id);
 }
 export function createEstuarineMap(std) {
     const gfx = gfxOf(std);
     if (!gfx.surface)
         return;
-    const width = EST_W * MAP_SCALE;
-    const height = EST_H * MAP_SCALE;
-    const { centerX, centerY } = gfx.viewport;
-    const id = gfx.surface.addElement({
-        type: 'estuarine',
-        // The map is this framework's ROOT INSTANCE: the role is what makes the
-        // Map quality checklist reachable on it (WS4). Cynefin's background gets
-        // none, on purpose — see `estuarine/roles.ts`.
-        role: ESTUARINE_ROLE.map,
-        xywh: new Bound(centerX - width / 2, centerY - height / 2, width, height).serialize(),
-    });
+    const id = gfx.surface.addElement(estuarineMapProps({
+        xywh: centered(gfx, ESTUARINE_MAP_W, ESTUARINE_MAP_H),
+    }));
     finish(gfx, id);
 }
 export function createConstraintHexagon(std) {
     const gfx = gfxOf(std);
     if (!gfx.surface)
         return;
-    const { centerX: cx, centerY: cy } = gfx.viewport;
-    const id = gfx.surface.addElement({
-        type: 'shape',
-        // A hexagon is a plain polygon on the canvas: nothing about its geometry
-        // says "constraint". The role is the only place that does.
-        role: ESTUARINE_ROLE.constraint,
-        shapeType: 'polygon',
-        vertices: HEX_VERTICES,
-        filled: true,
-        fillColor: HEX_FILL,
-        strokeColor: HEX_STROKE,
-        strokeWidth: 2,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        // hexi constraints behave like post-its: fixed hex, text shrinks
-        textFitMode: TextFitMode.Contained,
-        xywh: new Bound(cx - HEX_SIZE / 2, cy - HEX_SIZE / 2, HEX_SIZE, HEX_SIZE).serialize(),
-    });
+    const { centerX, centerY } = gfx.viewport;
+    const id = gfx.surface.addElement(estuarineHexagonProps({ xywh: estuarineHexagonBox(centerX, centerY) }));
     finish(gfx, id);
 }

package/dist/presets.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What a Cynefin / Estuarine artefact IS, as props — the ONE description the
+ * creation actions and the templates both read.
+ *
+ * Split out of `actions.ts` for the reason Wardley's and BPMN's `presets.ts`
+ * give: the palette used to restate these props by hand and drifted the moment
+ * the toolbox moved. The hexagon lost the `textFitMode` that #52 gave it, and
+ * the estuarine background was drawn at scale 1 while the button drew it at
+ * 1.2. Derived from one table, neither can happen again.
+ */
+/** Estuarine map default scale (REF aspect, scaled up so it reads on canvas). */
+export declare const MAP_SCALE = 1.2;
+/** The box an estuarine map is born in — the size the toolbox draws. */
+export declare const ESTUARINE_MAP_W: number;
+export declare const ESTUARINE_MAP_H: number;
+/** The box a Cynefin frame is born in. */
+export declare const CYNEFIN_W = 1080;
+export declare const CYNEFIN_H = 777;
+/**
+ * The Cynefin frame, as props.
+ *
+ * NO role, deliberately and for good: the framework is out of the validation
+ * perimeter (PO, 26/08/2026 — see `estuarine/roles.ts`). Stated here once so
+ * the neutrality is a decision rather than an omission on either side.
+ */
+export declare function cynefinBackgroundProps(box: {
+    xywh: string;
+}): Record<string, unknown> & {
+    type: string;
+};
+/**
+ * The estuarine map, as props.
+ *
+ * The map is this framework's ROOT INSTANCE: the role is what makes the Map
+ * quality checklist reachable on it (WS4).
+ */
+export declare function estuarineMapProps(box: {
+    xywh: string;
+}): Record<string, unknown> & {
+    type: string;
+};
+/**
+ * A hexi constraint, as props.
+ *
+ * A hexagon is a plain polygon on the canvas: nothing about its geometry says
+ * "constraint". The role is the only place that does. The fit mode is the other
+ * half of the notation — a constraint behaves like a post-it, fixed hex, text
+ * shrinks — and it is exactly what the palette had lost.
+ */
+export declare function estuarineHexagonProps(box: {
+    xywh: string;
+}): Record<string, unknown> & {
+    type: string;
+};
+/** The box a hexagon is born in, centred on a point. */
+export declare function estuarineHexagonBox(cx: number, cy: number): string;

package/dist/presets.js

@@ -0,0 +1,71 @@
+import { ShapeStyle, TextFitMode } from '@formicoidea/labre-core/model';
+import { REF_H as CYN_H, REF_W as CYN_W } from './cynefin/consts.js';
+import { HEX_FILL, HEX_SIZE, HEX_STROKE, HEX_VERTICES, REF_H as EST_H, REF_W as EST_W, } from './estuarine/consts.js';
+import { ESTUARINE_ROLE } from './estuarine/roles.js';
+/**
+ * What a Cynefin / Estuarine artefact IS, as props — the ONE description the
+ * creation actions and the templates both read.
+ *
+ * Split out of `actions.ts` for the reason Wardley's and BPMN's `presets.ts`
+ * give: the palette used to restate these props by hand and drifted the moment
+ * the toolbox moved. The hexagon lost the `textFitMode` that #52 gave it, and
+ * the estuarine background was drawn at scale 1 while the button drew it at
+ * 1.2. Derived from one table, neither can happen again.
+ */
+/** Estuarine map default scale (REF aspect, scaled up so it reads on canvas). */
+export const MAP_SCALE = 1.2;
+/** The box an estuarine map is born in — the size the toolbox draws. */
+export const ESTUARINE_MAP_W = EST_W * MAP_SCALE;
+export const ESTUARINE_MAP_H = EST_H * MAP_SCALE;
+/** The box a Cynefin frame is born in. */
+export const CYNEFIN_W = CYN_W;
+export const CYNEFIN_H = CYN_H;
+/**
+ * The Cynefin frame, as props.
+ *
+ * NO role, deliberately and for good: the framework is out of the validation
+ * perimeter (PO, 26/08/2026 — see `estuarine/roles.ts`). Stated here once so
+ * the neutrality is a decision rather than an omission on either side.
+ */
+export function cynefinBackgroundProps(box) {
+    return { type: 'cynefin', xywh: box.xywh };
+}
+/**
+ * The estuarine map, as props.
+ *
+ * The map is this framework's ROOT INSTANCE: the role is what makes the Map
+ * quality checklist reachable on it (WS4).
+ */
+export function estuarineMapProps(box) {
+    return { type: 'estuarine', role: ESTUARINE_ROLE.map, xywh: box.xywh };
+}
+/**
+ * A hexi constraint, as props.
+ *
+ * A hexagon is a plain polygon on the canvas: nothing about its geometry says
+ * "constraint". The role is the only place that does. The fit mode is the other
+ * half of the notation — a constraint behaves like a post-it, fixed hex, text
+ * shrinks — and it is exactly what the palette had lost.
+ */
+export function estuarineHexagonProps(box) {
+    return {
+        type: 'shape',
+        role: ESTUARINE_ROLE.constraint,
+        shapeType: 'polygon',
+        // A fresh array of fresh pairs: this goes into a document, and two hexagons
+        // sharing one literal would be two elements sharing one array.
+        vertices: HEX_VERTICES.map(([x, y]) => [x, y]),
+        filled: true,
+        fillColor: HEX_FILL,
+        strokeColor: HEX_STROKE,
+        strokeWidth: 2,
+        shapeStyle: ShapeStyle.General,
+        roughness: 0,
+        textFitMode: TextFitMode.Contained,
+        xywh: box.xywh,
+    };
+}
+/** The box a hexagon is born in, centred on a point. */
+export function estuarineHexagonBox(cx, cy) {
+    return `[${cx - HEX_SIZE / 2},${cy - HEX_SIZE / 2},${HEX_SIZE},${HEX_SIZE}]`;
+}

package/dist/templates/index.js

@@ -1,8 +1,30 @@
-import { makeTemplateSnapshot, surfaceText, } from '@formicoidea/labre-core/gfx/template';
+import { makeTemplateSnapshot, surfaceText, templateFromCommand, } from '@formicoidea/labre-core/gfx/template';
 import { FontFamily, ShapeStyle, TextAlign } from '@formicoidea/labre-core/model';
-import { REF_H as CYN_H, REF_W as CYN_W } from '../cynefin/consts.js';
-import { HEX_FILL, HEX_SIZE, HEX_STROKE, HEX_VERTICES, REF_H as EST_H, REF_W as EST_W, } from '../estuarine/consts.js';
-import { ESTUARINE_ROLE } from '../estuarine/roles.js';
+import { cynefinEstuarineCommands } from '../commands.js';
+import { HEX_SIZE } from '../estuarine/consts.js';
+import { CYNEFIN_H, CYNEFIN_W, cynefinBackgroundProps, ESTUARINE_MAP_H, ESTUARINE_MAP_W, estuarineHexagonBox, estuarineHexagonProps, estuarineMapProps, MAP_SCALE, } from '../presets.js';
+/**
+ * The Cynefin / Estuarine palettes — DERIVED from the toolbox, one template per
+ * command.
+ *
+ * Every single-artefact entry below is what its command actually draws, run
+ * once against a recording surface. Hand-written, they had drifted exactly as
+ * far as a copy drifts: the hexagons had lost the `textFitMode` #52 gave them,
+ * and the estuarine background was drawn at scale 1 (690×801) where the button
+ * draws it at 1.2 (828×961). Derived, neither can happen again — and
+ * `templates-parity.unit.spec.ts` re-runs each command and compares.
+ *
+ * The two COMPOSITIONS stay hand-written: a sorting board and a constraint map
+ * are arrangements no single command draws. They are built on the same presets,
+ * and the same test checks their composition.
+ */
+/** The command a derived template is the picture of. Throws rather than skips. */
+function byId(id) {
+    const command = cynefinEstuarineCommands.find(entry => entry.id === id);
+    if (!command)
+        throw new Error(`[cynefin-estuarine] templates: no "${id}"`);
+    return command;
+}
 function sticky(x, y, text) {
     return {
         type: 'shape',
@@ -22,24 +44,31 @@ function sticky(x, y, text) {
         xywh: `[${x},${y},200,70]`,
     };
 }
-function hexagon(x, y) {
-    return {
-        type: 'shape',
-        // Same role the toolbox stamps (`actions.ts`): a template must produce the
-        // map a user would have drawn by hand, roles included.
-        role: ESTUARINE_ROLE.constraint,
-        shapeType: 'polygon',
-        vertices: HEX_VERTICES,
-        filled: true,
-        fillColor: HEX_FILL,
-        strokeColor: HEX_STROKE,
-        strokeWidth: 2,
-        shapeStyle: ShapeStyle.General,
-        roughness: 0,
-        xywh: `[${x},${y},${HEX_SIZE},${HEX_SIZE}]`,
-    };
-}
-function caption(x, y, str) {
+/**
+ * A constraint on the shipped map, placed by its CENTRE in the map's reference
+ * space (690×801) — the frame the drawing was laid out in — carried onto the
+ * box the map is actually born at.
+ */
+const hexAt = (cx, cy) => estuarineHexagonProps({
+    xywh: estuarineHexagonBox(cx * MAP_SCALE, cy * MAP_SCALE),
+});
+const CAPTION_W = 120;
+const CAPTION_H = 24;
+/** Room between a hexagon's bottom edge and the name under it. */
+const CAPTION_GAP = 8;
+/**
+ * The name UNDER the hexagon centred on the same point.
+ *
+ * The offset is `HEX_SIZE`, never a literal: this used to be a `+64` computed
+ * for a 60-wide hexagon, and #55 doubled the hexagon to 120 without touching
+ * it — so every caption ended up drawn INSIDE the shape it names. Derived, the
+ * caption follows the hexagon whatever size it is given next.
+ *
+ * Neutral, and staying so: a name is nobody's artefact.
+ */
+function caption(cx, cy, str) {
+    const x = cx * MAP_SCALE - CAPTION_W / 2;
+    const y = cy * MAP_SCALE + HEX_SIZE / 2 + CAPTION_GAP;
     return {
         type: 'text',
         text: surfaceText(str),
@@ -47,9 +76,10 @@ function caption(x, y, str) {
         fontFamily: FontFamily.Inter,
         fontSize: 16,
         textAlign: TextAlign.Center,
-        xywh: `[${x},${y},120,24]`,
+        xywh: `[${x},${y},${CAPTION_W},${CAPTION_H}]`,
     };
 }
+/** A hand-composed template — what is left once the artefacts are derived. */
 function tpl(name, preview, elements) {
     return {
         name,
@@ -59,41 +89,36 @@ function tpl(name, preview, elements) {
     };
 }
 const ATTRS = 'width="100%" height="100%" viewBox="0 0 135 80" xmlns="http://www.w3.org/2000/svg"';
-// Cynefin's background carries NO role, deliberately and for good: the
-// framework is out of the validation perimeter (PO, 26/08/2026). See
-// `estuarine/roles.ts`.
-const cynefinBg = (xywh) => ({ type: 'cynefin', xywh });
-const estuarineBg = (xywh) => ({
-    type: 'estuarine',
-    role: ESTUARINE_ROLE.map,
-    xywh,
-});
 export const cynefinTemplateCategory = {
     name: 'Cynefin',
     templates: [
         tpl('Decision sorting', `<svg ${ATTRS} fill="none"><rect x="8" y="10" width="119" height="60" rx="4" stroke="#2a9d99" stroke-width="1.5"/><path d="M67 10 V70 M8 40 H127" stroke="#9aa0a6"/><rect x="18" y="18" width="34" height="14" rx="2" fill="#fff3b0"/><rect x="83" y="18" width="34" height="14" rx="2" fill="#fff3b0"/><rect x="18" y="48" width="34" height="14" rx="2" fill="#fff3b0"/><rect x="83" y="48" width="34" height="14" rx="2" fill="#fff3b0"/></svg>`, {
-            bg: cynefinBg(`[0,0,${CYN_W},${CYN_H}]`),
+            bg: cynefinBackgroundProps({
+                xywh: `[0,0,${CYNEFIN_W},${CYNEFIN_H}]`,
+            }),
             s1: sticky(190, 175, 'Probe & learn'),
             s2: sticky(690, 175, 'Expert analysis'),
             s3: sticky(190, 505, 'Act now'),
             s4: sticky(690, 505, 'Known issue'),
         }),
-        tpl('Cynefin framework', `<svg ${ATTRS} fill="none"><rect x="14" y="12" width="107" height="56" rx="4" stroke="#2a9d99" stroke-width="1.6"/><path d="M67 12 V68 M14 40 H121" stroke="#9aa0a6"/></svg>`, { bg: cynefinBg(`[0,0,${CYN_W},${CYN_H}]`) }),
+        templateFromCommand(byId('cynefin-estuarine.addCynefin'), `<svg ${ATTRS} fill="none"><rect x="14" y="12" width="107" height="56" rx="4" stroke="#2a9d99" stroke-width="1.6"/><path d="M67 12 V68 M14 40 H121" stroke="#9aa0a6"/></svg>`, 'Cynefin framework'),
     ],
 };
 export const estuarineTemplateCategory = {
     name: 'Estuarine',
     templates: [
         tpl('Constraint map', `<svg ${ATTRS} fill="none"><path d="M20 12 V70 M20 70 H120" stroke="#941253" stroke-width="2"/><g fill="#34c724" stroke="#1f1f1f"><path d="M44 28 l6 4 l0 8 l-6 4 l-6 -4 l0 -8 z"/><path d="M74 40 l6 4 l0 8 l-6 4 l-6 -4 l0 -8 z"/><path d="M56 52 l6 4 l0 8 l-6 4 l-6 -4 l0 -8 z"/></g></svg>`, {
-            bg: estuarineBg(`[0,0,${EST_W},${EST_H}]`),
-            h1: hexagon(150, 220),
-            c1: caption(120, 284, 'Policy'),
-            h2: hexagon(330, 360),
-            c2: caption(300, 424, 'Habit'),
-            h3: hexagon(230, 520),
-            c3: caption(200, 584, 'Budget'),
+            bg: estuarineMapProps({
+                xywh: `[0,0,${ESTUARINE_MAP_W},${ESTUARINE_MAP_H}]`,
+            }),
+            h1: hexAt(210, 280),
+            c1: caption(210, 280, 'Policy'),
+            h2: hexAt(390, 420),
+            c2: caption(390, 420, 'Habit'),
+            h3: hexAt(290, 580),
+            c3: caption(290, 580, 'Budget'),
         }),
-        tpl('Estuarine map', `<svg ${ATTRS} fill="none"><path d="M24 10 V70 M24 70 H120" stroke="#941253" stroke-width="2.4"/><path d="M30 52 q40 -30 84 -34" stroke="#5ecc44" stroke-width="2" fill="none"/></svg>`, { bg: estuarineBg(`[0,0,${EST_W},${EST_H}]`) }),
-        tpl('Hexagon constraint', `<svg ${ATTRS} fill="none"><path d="M67 24 l18 11 l0 22 l-18 11 l-18 -11 l0 -22 z" fill="#34c724" stroke="#1f1f1f" stroke-width="2"/></svg>`, { hex: hexagon(0, 0) }),
+        templateFromCommand(byId('cynefin-estuarine.addEstuarineMap'), `<svg ${ATTRS} fill="none"><path d="M24 10 V70 M24 70 H120" stroke="#941253" stroke-width="2.4"/><path d="M30 52 q40 -30 84 -34" stroke="#5ecc44" stroke-width="2" fill="none"/></svg>`, 'Estuarine map'),
+        templateFromCommand(byId('cynefin-estuarine.addConstraintHexagon'), `<svg ${ATTRS} fill="none"><path d="M67 24 l18 11 l0 22 l-18 11 l-18 -11 l0 -22 z" fill="#34c724" stroke="#1f1f1f" stroke-width="2"/></svg>`, 'Hexagon constraint'),
     ],
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-framework-cynefin",
   "description": "Labre cynefin-estuarine framework for @formicoidea/labre-core.",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",
@@ -31,7 +31,7 @@
     "dist"
   ],
   "dependencies": {
-    "@formicoidea/labre-core": "0.37.0",
+    "@formicoidea/labre-core": "0.38.1",
     "@preact/signals-core": "^1.8.0",
     "lit": "^3.2.0"
   }