@formicoidea/labre-framework-wardley 0.34.2 → 0.36.0

package/dist/node/porter-watcher.js

@@ -0,0 +1,255 @@
+import { WardleyNodeElementModel } from '@formicoidea/labre-core/model';
+import { ELEMENT_TAGS_FIELD, elementTagValues, InteractivityExtension, setElementTag, } from '@formicoidea/labre-core/std/gfx';
+import { WARDLEY_COMPETITION_TAG_ID } from '../natures.js';
+import { competitionOfPorterLetter, porterLetterOfCompetition, } from '../porter-competition.js';
+/**
+ * Keeps a Porter's-forces glyph saying ONE thing: the letter in the circle and
+ * the `wardley:competition` tag on it are two spellings of the same statement.
+ *
+ * ## Why there are two spellings at all
+ *
+ * The letter is the NOTATION — an architect reads `L` off the map and knows
+ * what it says, and typing another letter is the whole of the edit
+ * (`node-view.ts`). The tag is the FACT — the half a rule, a reading or a host
+ * report can query, because nothing can ask "which forces does this map name?"
+ * of a `Y.Text` holding one character. Dropping either would cost something
+ * real, so both exist.
+ *
+ * ## The invariant: the tag is DERIVED from the letter
+ *
+ * The two are not symmetric, and the recette of #211 is what made the asymmetry
+ * necessary. The letter is what the author writes; the tag is a reading of it,
+ * recomputed on EVERY local change of the text and written as a consequence of
+ * that change rather than as a step of its own. So `tag = f(text)` holds at
+ * every instant, including at every instant an undo or a redo passes through.
+ *
+ * That is the fix for the defect the recette found. Reconciling only when the
+ * editor closed left the two able to disagree: the inline editor writes a
+ * select-all-and-retype as several Yjs operations, each its own undo entry,
+ * while the tag was one further entry captured after all of them. Undoing then
+ * landed on an intermediate text — `RR` — carrying the tag of the text that
+ * came after it, and redoing past the tag's own entry re-ran the reconciliation
+ * against a text that had already moved on, so the document never returned to
+ * where it started.
+ *
+ * The reading is taken on a MICROTASK after the change, and written UNTRACKED
+ * (`Store.withoutTransact`, an origin the undo manager ignores). So the undo
+ * stack holds the author's keystrokes and nothing else, and whatever text a
+ * step lands on — `E`, the intermediate `RR`, the original `R` — the tag is
+ * recomputed from it a tick later. There is no entry to get out of order,
+ * because the qualification is not an entry.
+ *
+ * ## Tag → letter, and why it is the quiet direction
+ *
+ * A menu pick is the one gesture that starts from the tag, so it — and only it
+ * — redraws the letter. Two guards keep that from becoming a second author:
+ *
+ * - It compares the two SEMANTICALLY (`competitionOfPorterLetter(raw)`), never
+ *   character by character. A circle reading `e` already says "struggle to
+ *   establish", so a tag derived from it must not turn round and rewrite it to
+ *   `E`. Without this the two directions would trade writes on every keystroke.
+ * - It never runs while the id is in the EDITING set. That is C4's lesson
+ *   (`C4TypeLineWatcher`): rewriting the text an author has their caret in
+ *   throws that caret, and no letter is worth it.
+ *
+ * The one deliberate asymmetry: a CLEARED tag leaves the circle alone. Removing
+ * a value from the menu is a statement about the qualification — "I no longer
+ * claim which force this is" — and not about a map somebody is still reading.
+ * The tie is re-tied by the next edit of the letter, which is the only gesture
+ * that ever asserts one.
+ *
+ * ## `local`, and always-on
+ *
+ * Both directions are LOCAL-only, for `EdgyRelationResolver`'s reason: without
+ * it every peer on a shared board would derive the same tag the moment a letter
+ * synced, giving N−1 of them an entry for a gesture they did not make.
+ *
+ * Registered by the RENDER half rather than the flag-gated one
+ * (`docs/adr/0009`): this creates no element, offers no button and adds no
+ * artefact to any map. It keeps an element ALREADY in the document coherent
+ * with itself, which a force drawn while the Wardley button was on must stay
+ * when the button goes off.
+ */
+export class WardleyPorterWatcher extends InteractivityExtension {
+    constructor() {
+        super(...arguments);
+        this._selection = null;
+        this._updated = null;
+        this._disposeSurface = null;
+        this._editing = new Set();
+        this._pending = new Set();
+        this._scheduled = false;
+        this._mounted = false;
+    }
+    static { this.key = 'wardley-porter-watcher'; }
+    mounted() {
+        this._mounted = true;
+        // The editing set is tracked for ONE purpose: to know whose caret is where,
+        // so the tag→letter direction never rewrites a circle somebody is inside.
+        this._selection = this.gfx.selection.slots.updated.subscribe(selections => {
+            this._editing = wardleyEditingIds(selections);
+        });
+        // The surface is a SIGNAL — null at mount on a document whose surface block
+        // has not arrived yet, and replaced when it is. Subscribing to the signal
+        // rather than reading it once is what `EdgyRelationResolver` does, and for
+        // the same reason: a subscription taken against a surface that no longer
+        // exists is a subscription to nothing.
+        this._disposeSurface = this.gfx.surface$.subscribe(surface => {
+            this._updated?.unsubscribe();
+            this._updated = null;
+            if (!surface)
+                return;
+            this._updated = surface.elementUpdated.subscribe(({ id, props, local }) => {
+                if (!local || !props)
+                    return;
+                // `watchText` bridges the nested `Y.Text` under this key, so this is
+                // every change of the letter — a keystroke, an undo, a redo alike.
+                if ('text' in props)
+                    this._scheduleDerive(id);
+                // `observeTags` republishes the nested map under the field's own key,
+                // so this is the one payload a qualification produces.
+                if (ELEMENT_TAGS_FIELD in props)
+                    this._drawLetterFromTag(id);
+            });
+        });
+    }
+    unmounted() {
+        this._mounted = false;
+        this._pending.clear();
+        this._selection?.unsubscribe();
+        this._selection = null;
+        this._updated?.unsubscribe();
+        this._updated = null;
+        this._disposeSurface?.();
+        this._disposeSurface = null;
+        this._editing = new Set();
+        super.unmounted();
+    }
+    /** The porter this id names, when it is one this peer may rewrite. */
+    _porter(elementId) {
+        // A read-only document is READ: every write below would be refused, and
+        // nobody can have typed a letter into it in the first place.
+        if (this.std.store.readonly)
+            return null;
+        const element = this.gfx.surface?.getElementById(elementId);
+        if (!(element instanceof WardleyNodeElementModel))
+            return null;
+        if (element.kind !== 'porter')
+            return null;
+        if (element.isLocked())
+            return null;
+        return element;
+    }
+    /**
+     * Queue a re-reading of the letter, for the end of the current task.
+     *
+     * A MICROTASK, and it is load-bearing rather than cosmetic. `watchText` fires
+     * from inside the Yjs transaction that changed the text, and at that instant
+     * the element's own `Y.Map` observer may not have run yet — so `element.tags`
+     * can still resolve, through `_preserved`, to a nested map the very same
+     * transaction has just deleted. A tag written into that map goes nowhere at
+     * all: the recette of #211 saw exactly that, as an undo landing on a letter
+     * whose force had silently failed to follow it.
+     *
+     * Deferring past the transaction settles two things at once. The document is
+     * consistent when the reading is taken, and the write lands OUTSIDE any
+     * tracked transaction — so {@link Store.withoutTransact} really does keep it
+     * off the undo stack, and the tag becomes what it claims to be: a pure
+     * function of the text, recomputed after every change of it, in either
+     * direction of history, and never a step an author has to undo.
+     */
+    _scheduleDerive(elementId) {
+        this._pending.add(elementId);
+        if (this._scheduled)
+            return;
+        this._scheduled = true;
+        queueMicrotask(() => {
+            this._scheduled = false;
+            const ids = [...this._pending];
+            this._pending.clear();
+            if (!this._mounted)
+                return;
+            for (const id of ids)
+                this._deriveTagFromText(id);
+        });
+    }
+    /** The letter as it now stands, written down as the fact it states. */
+    _deriveTagFromText(elementId) {
+        const element = this._porter(elementId);
+        if (!element)
+            return;
+        const value = competitionOfPorterLetter(element.text?.toString());
+        // Anything that is not one of the three — a half-typed `RR`, a stray word,
+        // an emptied circle — carries no tag. A glyph nobody can read must not be
+        // reported as a force somebody named, and an INTERMEDIATE state an undo
+        // stops on is exactly such a glyph.
+        const next = value ? [value] : [];
+        const current = elementTagValues(element, WARDLEY_COMPETITION_TAG_ID);
+        if (current.length === next.length &&
+            current.every((v, i) => v === next[i]))
+            return;
+        // No `captureSync`, and UNTRACKED. The tag is a consequence of the letter,
+        // never a step of its own: `withoutTransact` writes with an origin the undo
+        // manager ignores, so an author undoes the letter they typed and the
+        // reading of it simply follows, in either direction, for ever.
+        this.std.store.withoutTransact(() => {
+            setElementTag(element, WARDLEY_COMPETITION_TAG_ID, next);
+        });
+    }
+    /** The value just picked from the menu, drawn as the letter it stands for. */
+    _drawLetterFromTag(elementId) {
+        const element = this._porter(elementId);
+        if (!element)
+            return;
+        // Never into a circle somebody has their caret in (`C4TypeLineWatcher`).
+        if (this._editing.has(elementId))
+            return;
+        const value = elementTagValues(element, WARDLEY_COMPETITION_TAG_ID)[0];
+        const letter = porterLetterOfCompetition(value);
+        // A cleared tag — and a value whose def has vanished, which has no letter
+        // either — leaves the circle exactly as it is. See the class comment: this
+        // is the one deliberate asymmetry.
+        if (!letter)
+            return;
+        const text = element.text;
+        if (!text)
+            return;
+        const raw = text.toString();
+        // SEMANTICALLY, not character by character: a circle reading `e` already
+        // says this value, and rewriting it to `E` would be this watcher answering
+        // its own derivation on every keystroke.
+        if (competitionOfPorterLetter(raw) === value)
+            return;
+        // No `captureSync` either: this only ever runs as a consequence of the tag
+        // write that caused it, and it nests into that write's transaction — so a
+        // menu pick costs exactly one undo entry, redrawing included.
+        //
+        // Mutated IN PLACE rather than replaced, as `C4TypeLineWatcher` does: the
+        // `Y.Text` instance is what the element's change watcher and any bound
+        // editor hold, and swapping it for a fresh one would leave both pointing at
+        // a text nobody is editing.
+        this.std.store.transact(() => {
+            text.delete(0, text.length);
+            text.insert(0, letter);
+        });
+    }
+}
+/**
+ * The ids currently being EDITED, out of a selection update.
+ *
+ * A pure function because it is the whole of what the watcher needs to know
+ * about the selection: a text editor holds an editing selection for as long as
+ * it is mounted and drops it when it closes, so this set is "whose caret is in
+ * something right now" and nothing else. Total over an empty selection, which
+ * is what arrives when an editor closes onto bare canvas.
+ */
+export function wardleyEditingIds(selections) {
+    const editing = new Set();
+    for (const selection of selections) {
+        if (!selection.editing)
+            continue;
+        for (const id of selection.elements)
+            editing.add(id);
+    }
+    return editing;
+}

package/dist/porter-competition.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The letter and the tag, in both directions — the whole of what makes the
+ * drawing and the qualification say the same thing.
+ *
+ * A pure module on purpose: this is the only place where the notation
+ * (`R` / `L` / `E`, one character in a circle) and the queryable fact
+ * (`wardley:competition/...`) are related to one another, and it is the part of
+ * `WardleyPorterWatcher` worth being wrong about. Nothing here reads an
+ * element, a surface or a document.
+ */
+/** The three letters the notation admits, and nothing else. */
+export type WardleyPorterLetter = 'R' | 'L' | 'E';
+/**
+ * What a competition value is written as, `null` when it is not one of the
+ * three.
+ *
+ * Total over anything a DOCUMENT can carry, not just over the ids this pack
+ * declares: defs are runtime configuration and are never persisted, so a board
+ * may legitimately hold a value whose pack was removed or renamed. Such a value
+ * has no letter, and the watcher leaves the circle alone rather than guessing
+ * one.
+ */
+export declare function porterLetterOfCompetition(valueId: string | null | undefined): WardleyPorterLetter | null;
+/**
+ * The competition value a circle's text states, `null` when it states none.
+ *
+ * Deliberately forgiving in exactly two ways and strict everywhere else. It
+ * trims — the shape editor keeps whatever whitespace the author left — and it
+ * upper-cases, because `l` is the same force as `L` and refusing it would make
+ * the qualification depend on a shift key. It then demands EXACTLY one of the
+ * three letters: `RL` is not a force, `X` is not a force, and neither is an
+ * empty circle. Anything else clears the tag rather than picking the nearest
+ * value, because a glyph nobody can read must not be reported as a force
+ * somebody named.
+ */
+export declare function competitionOfPorterLetter(text: string | null | undefined): string | null;

package/dist/porter-competition.js

@@ -0,0 +1,50 @@
+import { WARDLEY_COMPETITION } from './natures.js';
+const LETTER_OF_VALUE = {
+    [WARDLEY_COMPETITION.relative]: 'R',
+    [WARDLEY_COMPETITION.struggle]: 'L',
+    [WARDLEY_COMPETITION.establish]: 'E',
+};
+const VALUE_OF_LETTER = {
+    R: WARDLEY_COMPETITION.relative,
+    L: WARDLEY_COMPETITION.struggle,
+    E: WARDLEY_COMPETITION.establish,
+};
+/**
+ * What a competition value is written as, `null` when it is not one of the
+ * three.
+ *
+ * Total over anything a DOCUMENT can carry, not just over the ids this pack
+ * declares: defs are runtime configuration and are never persisted, so a board
+ * may legitimately hold a value whose pack was removed or renamed. Such a value
+ * has no letter, and the watcher leaves the circle alone rather than guessing
+ * one.
+ */
+export function porterLetterOfCompetition(valueId) {
+    if (typeof valueId !== 'string')
+        return null;
+    // A null-prototype lookup would be tidier, but the table is a literal and
+    // `Object.hasOwn` is what stops `'toString'` resolving to a letter.
+    return Object.hasOwn(LETTER_OF_VALUE, valueId)
+        ? LETTER_OF_VALUE[valueId]
+        : null;
+}
+/**
+ * The competition value a circle's text states, `null` when it states none.
+ *
+ * Deliberately forgiving in exactly two ways and strict everywhere else. It
+ * trims — the shape editor keeps whatever whitespace the author left — and it
+ * upper-cases, because `l` is the same force as `L` and refusing it would make
+ * the qualification depend on a shift key. It then demands EXACTLY one of the
+ * three letters: `RL` is not a force, `X` is not a force, and neither is an
+ * empty circle. Anything else clears the tag rather than picking the nearest
+ * value, because a glyph nobody can read must not be reported as a force
+ * somebody named.
+ */
+export function competitionOfPorterLetter(text) {
+    if (typeof text !== 'string')
+        return null;
+    const letter = text.trim().toUpperCase();
+    return Object.hasOwn(VALUE_OF_LETTER, letter)
+        ? VALUE_OF_LETTER[letter]
+        : null;
+}

package/dist/presets.d.ts

@@ -0,0 +1,276 @@
+import { type WardleyNodeKind } from '@formicoidea/labre-core/model';
+/**
+ * What a Wardley artefact IS, as props — the ONE description the creation sites
+ * and the morph both read.
+ *
+ * Split out of `actions.ts` when the morph landed, for the reason C4's and
+ * BPMN's `presets.ts` give: a kind's appearance is written by the preset of the
+ * kind it was CREATED as and nothing else ever rewrites it, so a morph that
+ * restated the table would agree with the palette the day it was written and
+ * drift on the first restyle. Derived, they cannot — a component morphed into a
+ * market and one drawn from the sub-menu are the same element.
+ *
+ * The three pieces that are not artefacts live here too, and for the same
+ * reason: the pipeline's HANDLE, the market's three neutral DOTS and the
+ * triangle that wires them are glyph parts, and the morph has to be able to
+ * build and unbuild them exactly as `createWardleyMarket` /
+ * `createWardleyPipeline` build them once.
+ */
+/**
+ * Every kind a user can draw — {@link WardleyNodeKind} minus the `handle`.
+ *
+ * The handle is not an artefact: it is the square that straddles a pipeline's
+ * top edge so connectors have somewhere to land (the body itself declares
+ * `connectable === false`). Nobody picks one from the palette, nothing may morph
+ * into one, and {@link wardleyHandleProps} is how the two composites that need
+ * one ask for it.
+ */
+export type WardleyArtefactKind = Exclude<WardleyNodeKind, 'handle'>;
+/**
+ * The size a kind is BORN at, which for Wardley is the notation rather than a
+ * default.
+ *
+ * A market is 30 across and a component is 18 because that is what tells a
+ * reader which is which — the two are the same white circle otherwise. Same for
+ * the ecosystem's 40 and the pipeline's 120×25 bar. This is the table the morph
+ * re-centres an artefact on, and the one the palette draws from.
+ */
+export declare const WARDLEY_NODE_SIZE: Record<WardleyArtefactKind, {
+    w: number;
+    h: number;
+}>;
+/** The two shapes one area kind is drawn as: a plain zone, or one with corners. */
+export type WardleyAreaShape = 'rect' | 'polygon';
+/**
+ * The size an area is born at, per shape.
+ *
+ * Beside {@link WARDLEY_NODE_SIZE} rather than in it, because the table above
+ * is keyed by KIND and these two artefacts are one kind: a rectangle 240 × 160
+ * covers a band of the map, and the polygon is born square so its default
+ * pentagon is regular. `WARDLEY_NODE_SIZE.area` is the rect's, so anything that
+ * asks a kind for its canonical box — the morph does — still gets an answer.
+ */
+export declare const WARDLEY_AREA_SIZE: Record<WardleyAreaShape, {
+    w: number;
+    h: number;
+}>;
+/**
+ * Every kind that is created NEXT TO a name — {@link WardleyArtefactKind} minus
+ * the `porter` and the `area`.
+ *
+ * Those two are the artefacts with no label ELEMENT at all, and narrowing the
+ * key type is how that is said rather than an empty string parked in the table
+ * below. An empty string would be a name the author has not typed yet, which is
+ * exactly what the placeholders ARE and exactly what the morph is allowed to
+ * rewrite; a force's letter is the notation and belongs to nobody's vocabulary,
+ * and a zone's name is written INSIDE the zone, so a placeholder there would be
+ * a word the author has to delete before typing their own.
+ */
+export type WardleyLabelledKind = Exclude<WardleyArtefactKind, 'porter' | 'area'>;
+/**
+ * The words a kind is created NEXT TO — the prompt an artefact nobody has named
+ * still carries, and the only string a morph is ever allowed to rewrite.
+ */
+export declare const WARDLEY_NODE_LABEL: Record<WardleyLabelledKind, string>;
+/** A box centred on a point — how every Wardley creation site places a node. */
+export declare function wardleyCenteredBox(cx: number, cy: number, w: number, h: number): string;
+/** The canonical box of one kind, centred where the artefact already stands. */
+export declare function wardleyCanonicalBox(kind: WardleyArtefactKind, cx: number, cy: number): string;
+/**
+ * Every prop a Wardley node is created with, for one kind and one box.
+ *
+ * Most of the pack is a native ELLIPSE and differs only in fill and size: the
+ * glyph — the anchor's silhouette, the ecosystem's hatched donut, the method's
+ * inner circle — is drawn by the renderer from `kind`, off this same model, so
+ * stroke and fill stay editable from the shape toolbar exactly like any other
+ * shape's. Two families are the exception, and they are the reason `clearOf`
+ * exists on this pack: the pipeline and the area are RECTS and the only kinds
+ * that write `radius`, and the accelerator / decelerator are POLYGONS — the
+ * only kinds that write `vertices` and `isClosed` from here.
+ *
+ * No `text`: a Wardley label is a separate free-text element grouped with the
+ * node (see `addLabel` in `actions.ts`), never words stored on the shape. The
+ * porter and the area are the two exceptions, and neither writes it HERE: their
+ * inner text is content the author types, added at the creation site.
+ */
+export declare function wardleyNodeProps(kind: WardleyArtefactKind, box: {
+    xywh: string;
+}): Record<string, unknown> & {
+    type: string;
+};
+/**
+ * An AREA, as props — one kind, two shapes.
+ *
+ * The second discriminator this pack needed, and the reason it is a parameter
+ * rather than a second `kind`: a rectangular zone and a polygonal one are the
+ * same statement about the map ("all of this is one thing"), drawn with a
+ * different number of corners. A second kind would have to be kept in step in
+ * the role table, the legend, the export and the morph's key union, for a
+ * difference the `shapeType` already carries.
+ *
+ * Everything but the outline comes from {@link wardleyNodeProps}, which is the
+ * house rule: the fill, the rim and the role are the area's, wherever it is
+ * built from. What is added here is the two shapes and the fact that an area's
+ * NAME is its own inner text.
+ *
+ * ## The text is the name, and the zone never grows to fit it
+ *
+ * `TextFitMode.Overflow`, exactly as the porter's letter and the inertia bar:
+ * an area is a boundary drawn around real components, so a long name must never
+ * push that boundary out and swallow a component the author did not mean to
+ * include. Top-left, because a zone's name belongs in its corner rather than
+ * across the middle of the map it covers — and no `text` at all, so the editor
+ * a double-click opens starts on an empty line.
+ */
+export declare function wardleyAreaProps(shape: WardleyAreaShape, box: {
+    xywh: string;
+}): Record<string, unknown> & {
+    type: string;
+};
+/** Where an area of the given shape is born, centred on a point. */
+export declare function wardleyAreaBox(shape: WardleyAreaShape, cx: number, cy: number): string;
+/**
+ * The pipeline's handle: a node-sized square straddling the body's top edge, and
+ * the only place a connector may land on a pipeline.
+ *
+ * It inherits `centerAnchorOnly` from the model like every other Wardley node,
+ * and it carries `wardley:handle` — a role of its own, so nothing that judges
+ * components ever judges it.
+ */
+export declare function wardleyHandleProps(box: {
+    xywh: string;
+}): Record<string, unknown> & {
+    type: string;
+};
+/** Where a handle sits, given the body's centre: astride the top edge. */
+export declare function wardleyHandleBox(cx: number, cy: number): string;
+/**
+ * One of the market's three inner dots — thicker-bordered, and deliberately
+ * ROLE-LESS.
+ *
+ * They are the GLYPH's own wiring rather than artefacts the user placed, the
+ * same reason the triangle between them carries no role: they sit inside the
+ * market circle by construction, so a role would make every market composite
+ * report an overlap with itself (W3).
+ */
+export declare function wardleyMarketDotProps(box: {
+    xywh: string;
+}): Record<string, unknown> & {
+    type: string;
+};
+/** The three dot boxes of a market centred on (cx, cy) — an upright triangle. */
+export declare function wardleyMarketDotBoxes(cx: number, cy: number): string[];
+/**
+ * One side of the market's triangle: an ATTACHED connector, so it auto-routes
+ * centre to centre and follows the dots on move and resize.
+ */
+export declare function wardleyMarketLinkProps(sourceId: string, targetId: string): Record<string, unknown> & {
+    type: string;
+};
+/** The pairs the triangle wires, given the three dots in creation order. */
+export declare function wardleyMarketLinkPairs<T>(dots: readonly T[]): [T, T][];
+/** One of the four arrows: its own axis-aligned box, and the outline in it. */
+export interface WardleyPorterArrow {
+    /** Serialized `xywh` of the box the polygon is drawn inside. */
+    xywh: string;
+    /** The outline as normalized [0-1] coordinates of that box, tip first. */
+    vertices: number[][];
+}
+/**
+ * The four arrows of a Porter's-forces glyph, for a circle of the given radius
+ * centred on (cx, cy) — a box and an outline each.
+ *
+ * The ONE description of the geometry, so the creation site, the map legend and
+ * the tests read the same numbers rather than three sets that agreed the day
+ * they were written. Each arrow starts `PORTER_ARROW.gap` clear of the rim —
+ * the arrows push against the circle, they do not touch it — and runs
+ * `PORTER_ARROW.length` further out, tip at the far end.
+ *
+ * Every distance scales WITH the radius, and that is what makes a legend row the
+ * same drawing at another size: a 12-unit glyph carrying four map-sized arrows
+ * would not be a small Porter, it would be a circle somebody stabbed.
+ */
+export declare function wardleyPorterArrows(cx: number, cy: number, radius?: number): WardleyPorterArrow[];
+/**
+ * One of those arrows as props: a filled POLYGON on a `wardleyNode`, and
+ * deliberately ROLE-LESS.
+ *
+ * A polygon and not a connector, which is the first fix the recette of #210
+ * asked for: a connector's triangle head is sized off its stroke width, so the
+ * heads arrived longer than the arrows and covered the circle, the letter and
+ * the double-click target. A polygon's outline is exactly the seven points
+ * above.
+ *
+ * A `wardleyNode` and not a plain `shape`, which is the second: recette v2
+ * found that `ShapeElementView` gives EVERY plain shape a double-click that
+ * mounts the inner-text editor, and mounting it grew an arrow from 24 units
+ * high to 44 — a deformation that survived Escape. An arrow is not a thing you
+ * write in. Posting it as a `wardleyNode` moves it onto `WardleyNodeView`,
+ * which opens an editor only on the artefact that HAS a letter; the renderer is
+ * unaffected, because a Wardley node draws itself through the native shape
+ * renderer and that renderer already dispatches on `shapeType`.
+ *
+ * Role-less, and `kind: 'porter'` with it, for the reason the market's three
+ * inner dots already give — they are `kind: 'component'` and carry no role: this
+ * is the glyph's own wiring rather than anything the author drew, so a role
+ * would make every composite report an overlap with itself (W3), would offer
+ * four arrows to the OWM writer, and would let a stray label bind to one.
+ * `undefined` writes no key at all, exactly as it does for those dots.
+ *
+ * Filled rather than stroked, so nothing about them is sized off a line width
+ * ever again.
+ */
+export declare function wardleyPorterArrowProps(arrow: WardleyPorterArrow): Record<string, unknown> & {
+    type: string;
+};
+/**
+ * The letter inside the circle, as shape-text props.
+ *
+ * A plain STRING and not a `Y.Text`: `ShapeElementModel.propsToY` builds the
+ * Y type on the way into the document, and this package depends on yjs only in
+ * its tests. `TextFitMode.Overflow` is the load-bearing line — the glyph has a
+ * canonical size that says "external force" at a glance, so the circle must
+ * never grow to fit whatever the author types into it, exactly as the inertia
+ * bar never deforms around its own text.
+ */
+export declare function wardleyPorterLetterProps(letter: string, fontSize?: number): Record<string, unknown>;
+/**
+ * What a kind is worth to a node that ALREADY EXISTS — {@link wardleyNodeProps}
+ * minus the three things a morph has no business touching.
+ *
+ * The whole preset and not `{kind, role}`, and on this pack it is visibly not a
+ * formality: a pipeline is a rect with square corners and a semi-transparent
+ * fill, and the other three members of the family are opaque white ellipses. A
+ * two-key patch would turn a component into a "pipeline" still drawn as a
+ * circle.
+ */
+export declare function wardleyMorphProps(kind: WardleyArtefactKind): Record<string, unknown>;
+/**
+ * The kinds that can actually MORPH — the one family `morph.ts` declares.
+ *
+ * Restated here rather than imported, and that is a circular-import dodge with
+ * a real reason behind it: `morph.ts` reads this module for the presets, so
+ * this module cannot read it back. `morph.unit.spec.ts` asserts the two lists
+ * are the same set, so the restatement cannot drift.
+ *
+ * It exists because {@link wardleyMorphClears} needs a UNION, and a union over
+ * the whole pack is the wrong one. Since the accelerator and the decelerator
+ * joined it, "every key any kind writes" includes `vertices` and `isClosed` —
+ * keys of two POLYGONS that are in no family and that nothing may ever morph
+ * into. Left unrestricted, morphing a market back to a component would emit a
+ * delete for `vertices` on an ellipse that never had one: harmless today, and a
+ * patch that says something untrue about the pack the day a morphable kind
+ * gains an outline.
+ */
+export declare const WARDLEY_MORPHABLE_KINDS: readonly WardleyArtefactKind[];
+/**
+ * The fields to DELETE after morphing to `kind` — the keys some other kind
+ * writes and this one does not.
+ *
+ * `radius` for every kind but the pipeline, and that is not a formality either:
+ * a patch cannot express absence, so a pipeline morphed back to a component
+ * would keep `radius: 0` sitting in the Y.Map, silently in force on an ellipse.
+ * Derived rather than listed, so the day a preset gains a conditional key it is
+ * covered without anybody remembering to come here.
+ */
+export declare function wardleyMorphClears(kind: WardleyArtefactKind): readonly string[];