@formicoidea/labre-framework-wardley 0.43.1 → 0.46.0

package/dist/commands.js

@@ -372,13 +372,19 @@ const exportCommand = {
  * and invocable by an agent.
  *
  * **Flagged for the PO** as a curation call rather than a technical one: it is
- * a one-line change either way.
+ * a one-line change either way. ADR 0032 (open point 4) asked again once the
+ * reader started yielding a map, and the answer stayed: the catalogue.
  *
  * ## The label names the tier before the file is read
  *
- * A map is coordinates, and this reader recovers none: it recognises circles
- * and words. Saying so in the description is not modesty, it is the contract —
- * "the import surface must name the tier before the file is read".
+ * The description says which producers' pictures arrive as a MAP and that
+ * everything else arrives as a sketch — "the import surface must name the tier
+ * before the file is read". It is a new key, and the old one
+ * (`com.labre.commands.wardley.importSvg.description`, "The axes and the
+ * evolution are not read…") is retired rather than reworded: a host's
+ * translation of it says the opposite of what the reader now does, and a
+ * reworded fallback would have left that translation lying (ADR 0032,
+ * Consequences).
  */
 const importSvgCommand = {
     id: 'wardley.importSvg',
@@ -386,8 +392,8 @@ const importSvgCommand = {
     kind: 'action',
     labelKey: 'com.labre.commands.wardley.importSvg',
     labelFallback: 'Import SVG sketch',
-    descriptionKey: 'com.labre.commands.wardley.importSvg.description',
-    descriptionFallback: 'Best effort: recognises shapes and text, no round-trip. The axes and the evolution are not read — what arrives is a sketch you then promote.',
+    descriptionKey: 'com.labre.commands.wardley.importSvg.recognised.description',
+    descriptionFallback: 'Best effort, no round-trip: a map exported as SVG by Labre or OnlineWardleyMaps, or drawn by wardley-map-renderer, arrives as a native Wardley map — components, links, pipelines, evolution. Any other map with its two axes drawn gives its components and links; everything else arrives as a sketch you then promote.',
     // The same section the two OWM directions are filed under, and the same one
     // BPMN files its `.bpmn` pair under: a host that translated the header once
     // has translated it for every framework.

package/dist/element-renderer.d.ts

@@ -12,6 +12,6 @@ import type { WardleyBackgroundElementModel } from '@formicoidea/labre-core/mode
  * suite drives it directly with a canvas stub.
  */
 export declare const wardley: ElementRenderer<WardleyBackgroundElementModel>;
-export declare const WardleyElementRendererExtension: import("@formicoidea/labre-core/store").ExtensionType & {
+export declare const WardleyElementRendererExtension: import("@formicoidea/labre-core/_pkgs/store").ExtensionType & {
     identifier: import("@formicoidea/labre-core/_pkgs/global/di").ServiceIdentifier<ElementRenderer<WardleyBackgroundElementModel>>;
 };

package/dist/element-view.d.ts

@@ -29,4 +29,4 @@ export declare class WardleyView extends DeclaredBackgroundView<WardleyBackgroun
  * `resizeEnabled` is true — the runtime half of the declaration's
  * `geometry.resizable`.
  */
-export declare const WardleyInteraction: import("@formicoidea/labre-core/store").ExtensionType;
+export declare const WardleyInteraction: import("@formicoidea/labre-core/_pkgs/store").ExtensionType;

package/dist/export.d.ts

@@ -172,18 +172,68 @@ export interface WardleyExportBoard {
 }
 export declare function wardleyBoardFrom(elements: readonly GfxPrimitiveElementModel[]): WardleyExportBoard;
 /**
- * A name a file system will accept, minus the extension. BPMN's sanitizer,
- * verbatim in behaviour and different only in its fallback — `map`, because
- * that is what an OWM document is.
+ * A name a file system will accept, minus the extension: the shared
+ * `safeFilename` with Wardley's fallback — `map`, because that is what an OWM
+ * document is. Held to it by `safe-filename-parity.unit.spec.ts`.
  */
 export declare function wardleySafeFilename(raw: string | undefined): string;
 /** The label box an import writes, and the width a prediction assumes. */
 export declare const OWM_LABEL_WIDTH = 200;
 export declare const OWM_LABEL_HEIGHT: number;
-/** A text element's string, whether it is a `Y.Text` or a test's plain one. */
-export declare function textOf(element: {
+/** What {@link matchLabels} reads of a node: a model, or a file's marker. */
+export interface LabelledNode {
+    id: string;
+    kind: string;
+    role?: string;
+    elementBound: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/** What {@link matchLabels} reads of a label. */
+export interface LabelBox {
     text?: unknown;
-}): string;
+    elementBound: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+/**
+ * Which label names which node — the one heuristic in this module.
+ *
+ * A name is a separate element on this canvas, so "which node is this the name
+ * of" is a question the document does not answer directly and the writer has to
+ * ask of the geometry. The naive answer — nearest node to the label box — is
+ * WRONG on a real map and provably so: two components 60 units apart
+ * horizontally and 17 apart vertically (which is nothing on a 1530-wide plot,
+ * and is exactly what the tea-shop corpus holds) put the lower one's centre
+ * INSIDE the upper one's label box, so it wins by a distance of half a unit and
+ * steals the name.
+ *
+ * What is asked instead is: how far is this label from where a label for this
+ * node WOULD have been written? A wrong node's answer is a whole node spacing;
+ * the right node's is the few units between one convention and another. Pairs
+ * within {@link LABEL_MATCH_TOLERANCE} are then assigned greedily, closest
+ * first, ties broken by document order — so the assignment is a function of the
+ * document and not of the iteration order.
+ *
+ * A pipeline HANDLE never claims a label: it sits on the body's top edge, right
+ * under the name the body owns, and would win every pipeline's name from it.
+ * A Porter's-forces glyph never claims one either, and for a sharper reason: it
+ * HAS no name — its one letter is the shape's own inner text — so any label it
+ * matched would be some neighbouring artefact's, taken out of that artefact's
+ * mouth and then thrown away, since a force is not written to the file at all.
+ *
+ * Typed on the four facts it reads rather than on the models, so the SVG
+ * reader (`svg-recognise-labre.ts`) names the nodes of Labre's own export with
+ * this very function, from the bounds the file's markers carry: an export and
+ * the import of that export cannot disagree about whose name is whose.
+ */
+export declare function matchLabels(nodes: readonly LabelledNode[], labels: readonly LabelBox[]): Map<string, string>;
 export interface WardleyOwmExportOptions {
     /** The board's own title, already sanitized by the caller. */
     name?: string;

package/dist/export.js

@@ -1,5 +1,6 @@
 import { backgroundPlot } from '@formicoidea/labre-core/blocks/surface';
 import { ConnectorElementModel, TextElementModel, WardleyBackgroundElementModel, WardleyNodeElementModel, } from '@formicoidea/labre-core/model';
+import { safeFilename } from '@formicoidea/labre-core/shared/utils';
 import { WARDLEY_BACKGROUND } from './background.js';
 import { LABEL_FONT_SIZE, LABEL_GAP } from './node/consts.js';
 import { WARDLEY_ROLE } from './roles.js';
@@ -265,19 +266,12 @@ export function wardleyBoardFrom(elements) {
     return { maps, nodes, labels, notes, connectors };
 }
 /**
- * A name a file system will accept, minus the extension. BPMN's sanitizer,
- * verbatim in behaviour and different only in its fallback — `map`, because
- * that is what an OWM document is.
+ * A name a file system will accept, minus the extension: the shared
+ * `safeFilename` with Wardley's fallback — `map`, because that is what an OWM
+ * document is. Held to it by `safe-filename-parity.unit.spec.ts`.
  */
 export function wardleySafeFilename(raw) {
-    const safe = (raw ?? '')
-        .trim()
-        .replaceAll(/[\\/:*?"<>|]/g, '-')
-        .replaceAll(/\s+/g, ' ')
-        .trim()
-        .slice(0, 120)
-        .replace(/[. ]+$/, '');
-    return safe || 'map';
+    return safeFilename(raw, 'map');
 }
 /* ── Matching a name to the artefact it names ─────────────────────────── */
 /** How far a label may sit from where this node's label belongs, in units. */
@@ -340,8 +334,13 @@ function labelAnchors(node, label) {
  * HAS no name — its one letter is the shape's own inner text — so any label it
  * matched would be some neighbouring artefact's, taken out of that artefact's
  * mouth and then thrown away, since a force is not written to the file at all.
+ *
+ * Typed on the four facts it reads rather than on the models, so the SVG
+ * reader (`svg-recognise-labre.ts`) names the nodes of Labre's own export with
+ * this very function, from the bounds the file's markers carry: an export and
+ * the import of that export cannot disagree about whose name is whose.
  */
-function matchLabels(nodes, labels) {
+export function matchLabels(nodes, labels) {
     const pairs = [];
     nodes.forEach((node, nodeIndex) => {
         // A handle sits on the pipeline body's top edge, directly under the name
@@ -379,7 +378,7 @@ function matchLabels(nodes, labels) {
     return byNode;
 }
 /** A text element's string, whether it is a `Y.Text` or a test's plain one. */
-export function textOf(element) {
+function textOf(element) {
     const text = element.text;
     return text === undefined || text === null ? '' : String(text);
 }

package/dist/import.d.ts

@@ -1,5 +1,5 @@
-import type { InterchangeImportContext, InterchangeImportResult } from '@formicoidea/labre-core/blocks/surface';
-import { OWM_SCOPE, WARDLEY_OWM_FORMAT_ID } from './export.js';
+import type { InterchangeImportContext, InterchangeImportResult, SerializedElementProps } from '@formicoidea/labre-core/blocks/surface';
+import type { ForeignInterchange } from '@formicoidea/labre-core/std/gfx';
 /**
  * The OWM import remarks whose wording is FIXED, as `[key, English]` pairs.
  *
@@ -29,114 +29,96 @@ export declare const WARDLEY_OWM_IMPORT_REMARKS: {
     readonly carriedConstruct: readonly ["com.labre.wardley.import.remark.carried-construct", "{{count}} `{{kind}}` line(s) kept verbatim on the map and written back on the next export. Nothing on this canvas draws them."];
 };
 /**
- * An OnlineWardleyMaps (OWM) DSL document, read as a Wardley map — the inverse
- * of `export.ts` on the vocabulary Labre draws, and an honest accounting of
- * everything else (`docs/adr/0012`, D1–D6).
+ * The keywords that declare a positioned artefact, and the kind each is.
  *
- * ADR 0012 calls this row **the reference Wardley import**, and says why: the
- * OWM DSL is the one Wardley vocabulary that is settled, so it is what a user
- * should be pointed at while mermaid's Wardley diagram type is still
- * experimental upstream.
- *
- * ## Pure by construction, like its mirror
- *
- * A string in, element PROPS out. No `BlockStdScope`, no surface, no DOM, no
- * clock, no randomness — and, unlike `.bpmn`, no parser either: the DSL is
- * line-based, so this reads lines. The caller does the writing (P3).
- *
- * ## What the caller owes, and it is one thing
- *
- * **OWM has no ids: the NAME is the identity.** So every element below carries
- * the name it was declared under, verbatim, in `interchange.owm.id`, and a link
- * arrives with `source` / `target` naming those — which is exactly the map
- * `materializeInterchangeImport` folds the returned array into (D3). Nothing
- * else is needed to finish the import, and the same fold is what makes
- * `boardFromProps` in the spec suite a bridge rather than a mock.
- *
- * A name declared twice is imported twice — nothing is dropped — and every link
- * naming it means the FIRST, which is both the materializer's rule and OWM's
- * own. The report says so by name.
- *
- * ## Where the coordinates come from, and where they do not (D4)
- *
- * A `[visibility, evolution]` pair IS the authoritative position — that is D4's
- * "a format that carries coordinates but no pixels" — so the reader projects it
- * onto the plot of the map it lays down and re-layouts nothing. A statement
- * that carries NO pair inverts the same rule rather than contradicting it:
- * there is nothing to be authoritative, so the reader lays one out and SAYS SO,
- * with an `invented-layout` note naming the artefact. **An invented axis is
- * never presented as read from the file.** That is the whole of D4 for a
- * coordinate format, and it is the case `anchor Client` — one line of the
- * tea-shop corpus, and the shape half the maps in the wild are written in.
- *
- * ## Three states, and the middle one is where the file survives
- *
- * **Mapped** is what the pack draws: `component`, `anchor`, `market`,
- * `ecosystem`, `accelerator`, `deaccelerator`, `pipeline`, `note`, `evolve`,
- * `title`, and the `->` links.
- * **Carried** is every other statement — `style`, `annotation`, `attitudes`
- * (`pioneers` / `settlers` / `townplanners`), `submap`, `url`, `size`,
- * the axis-label overrides, the flow links (`+>`, `+<`, `+<>`,
- * `+'…'>`), a link carrying a `;` context, and every `//` comment — kept
- * verbatim in `interchange.owm.children['@document']` on the map's background
- * element (D6) and written back, in order, at the end of the next export.
- * **Quarantined** is empty, and that is a finding rather than an omission: see
- * the loss table.
- *
- * A mapped line keeps its own tail too — `label [12, -8]`, `(build)`,
- * `inertia`, a trailing comment — under `attrs['@self'].tail` on the artefact
- * it belongs to, so the modifiers this pack does not draw come back on the
- * line they were written on rather than at the bottom of the file.
- *
- * ## The loss table
- *
- * Every semantic capability owes one (ADR 0012), and this is the OWM DSL's.
- * INVISIBLE is not LOST, and the distinction is the deliverable.
- *
- * | what                                                                   | state       | after a round trip                                                                                                     |
- * | ---------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
- * | `component` / `anchor` / `market` / `ecosystem` and their coordinates  | mapped      | drawn, and written back from the drawing, to two decimals                                                              |
- * | `accelerator` / `deaccelerator` and their coordinates                 | mapped      | drawn as the climate arrow, and written back under OWM's own spelling (`deaccelerator` for a decelerator)              |
- * | the NAME, which in this format is the identity                        | mapped      | given back verbatim, quoted exactly as it needs to be — the fixed point                                                |
- * | `pipeline Name [m1, m2]`                                              | mapped      | drawn as the body + handle composite; `[m1, m2]` written back from the body's two edges                                |
- * | `note Text [v, e]`                                                    | mapped      | a free text on the map, written back from its centre                                                                   |
- * | `evolve X [-> Y] m`                                                   | mapped      | an evolved twin at the same height plus a change arrow, written back from the arrow                                    |
- * | `A->B` links                                                          | mapped      | a `wardley:dependency` connector, consumer → what it needs, never inverted                                             |
- * | `title`                                                               | mapped      | consumed as the board's own name; written back from the board's name (see the two rows below)                          |
- * | a mapped line's TAIL — `label [x, y]`, `(build)`, `inertia`, comments | carried     | invisible on the canvas, re-appended to the very line it came off                                                      |
- * | `style`, `annotation(s)`, `attitudes`, `submap`, `url`, `size`, the axis-label overrides | carried | invisible on the canvas, re-emitted verbatim at the end of the file          |
- * | flow links (`+>`, `+<`, `+<>`, `+'…'>`) and a link with a `;` context | carried     | not drawn — a flow is not a dependency — and re-emitted verbatim                                                       |
- * | a `pipeline` with a `{ … }` body                                      | carried     | the block is kept whole and written back whole; the pack draws no pipeline children                                    |
- * | `//` comments                                                         | carried     | re-emitted verbatim, at the end                                                                                        |
- * | anything else the reader does not recognise                           | carried     | re-emitted verbatim, at the end                                                                                        |
- * | **nothing**                                                           | quarantined | every statement this format writes is a standalone sentence, so nothing carried can contradict the drawing (D5)        |
- * | a statement with NO coordinates (`anchor Client`)                     | **lost**    | the reader places it at the reference default (0.9, 0.1) and says so; the export then writes the coordinates we invented, not the silence the file had |
- * | a statement with MALFORMED coordinates                                | **lost**    | same, and the report carries a `warning` as well as the `invented-layout` note                                         |
- * | a statement positioned on ONE axis (`[0.5]`, `[nonsense, 0.5]`)       | **half mapped, half lost** | the axis the file gave is read and kept exactly; the other takes the reference default and gets its own `invented-layout` note naming WHICH axis was invented. The statement counts as `mapped` — it was positioned — and the export writes a full pair, so the axis the file left silent comes back as a number |
- * | the file's own line ORDER and its blank lines                         | **lost**    | the writer groups statements into sections. Nothing semantic depends on it, and carrying blank lines would make an untouched Labre file report a carried count |
- * | a `pipeline`'s visibility                                             | **lost**    | OWM derives it from the component of the same name; the reader places the body under that component and the writer does not write it back |
- * | an `evolve` twin drawn at a different height                          | **lost**    | `evolve` moves along the evolution axis only; the export warns                                                          |
- * | a Labre `method` node (build / buy / outsource)                       | **lost**    | written as a plain component — OWM says a method with a decorator this writer cannot tell apart. The export warns       |
- * | the file's `title`                                                    | **carried**, and it WINS | kept under `attrs['@document'].title` and written back in preference to the name the caller passes — D3's precedence, the same one `interchange.<fmt>.id` has on every element. A board renamed in Labre therefore still exports under the title its file carried, and the export warns that it did; the caller's name is used only when the file carried none (and is still what the DOWNLOAD is called either way) |
- * | surface identity across a re-import                                   | **lost**    | a new map beside the old one, never a merge                                                                            |
- * | a name whose whitespace matters (`Foo&nbsp;&nbsp;&nbsp;Bar`)          | **round-trips here, at risk elsewhere** | this reader keeps a name VERBATIM and this writer gives it back verbatim, so Labre → Labre is exact. onlinewardleymaps does not: `normalizeComponentName` collapses whitespace runs before it matches a link end to a component, so a map that goes Labre → OWM → Labre may come back with its links dangling. Not sanitized here, because sanitizing would lose the author's name to protect another tool's matcher |
- * | a top-level `market` / `ecosystem` statement                          | **round-trips here, refused elsewhere** | Labre reads and writes both. The reference `Converter` registers no strategy for either keyword, so such a line reaches `LinksExtractionStrategy`, has no `->` in it and is recorded as a PARSE ERROR — onlinewardleymaps does not merely fail to draw it. The interoperable spelling is a component carrying the decorator (`component Suppliers [0.3, 0.7] (market)`), which this pair already round-trips through the carried tail |
- *
- * `sourceVersion` reports the DIALECT, because the DSL declares no version: the
- * OnlineWardleyMaps frontend's own extraction strategies, which is what this
- * reader was written against. It reads `DSL (Labre)` for a file holding nothing
- * this library does not itself write — the honest form of "a file we wrote",
- * since the format has no marker to claim one with.
+ * `deaccelerator` is OWM's own spelling of a decelerator — the keyword the
+ * reference parser claims — so the KEY is the format's word and the VALUE is
+ * this canvas's kind. It is the one row where the two differ, and the reason
+ * this is a table rather than an identity.
+ */
+declare const NODE_KEYWORDS: {
+    readonly component: "component";
+    readonly anchor: "anchor";
+    readonly market: "market";
+    readonly ecosystem: "ecosystem";
+    readonly accelerator: "accelerator";
+    readonly deaccelerator: "decelerator";
+};
+export type WardleyNodeKeyword = keyof typeof NODE_KEYWORDS;
+type NodeKeyword = WardleyNodeKeyword;
+/**
+ * The statements a Wardley map is made of — what this reader builds out of
+ * lines, and what the SVG reader (`svg-import.ts`, ADR 0032 §2) builds out of
+ * a picture, so both are laid out by {@link layoutWardleyStatements} and a map
+ * that arrives from a file and one that arrives from a drawing are the same
+ * elements.
+ *
+ * `id` is the identity links, pipelines and `evolve` lines refer to. OWM has
+ * none — the NAME is the identity — so this reader leaves it out; a picture
+ * has ids of its own (an SVG producer's), and names that may repeat.
+ */
+export interface WardleyNodeStatement {
+    keyword: NodeKeyword;
+    name: string;
+    id?: string;
+    visibility: number;
+    evolution: number;
+    tail: string;
+    invented: boolean;
+}
+/**
+ * `id` / `name`: the identity and the name of the component it hangs under —
+ * or, with `top`, of the pipeline itself, standing alone with its body's top
+ * edge at that visibility (a picture that draws a pipeline as its own
+ * artefact; the DSL never does).
  */
-export { WARDLEY_OWM_FORMAT_ID, OWM_SCOPE };
+export interface WardleyPipelineStatement {
+    name: string;
+    id?: string;
+    from: number;
+    to: number;
+    top?: number;
+    tail: string;
+    invented: boolean;
+}
+export interface WardleyNoteStatement {
+    text: string;
+    visibility: number;
+    evolution: number;
+    tail: string;
+    invented: boolean;
+}
+/** `id` / `name`: the component that moves; `becomes`: its twin's name. */
+export interface WardleyEvolveStatement {
+    name: string;
+    id?: string;
+    becomes: string;
+    evolution: number;
+    tail: string;
+    invented: boolean;
+}
+/** Two identities: the consumer, then what it needs (ADR 0010). */
+export interface WardleyLinkStatement {
+    from: string;
+    to: string;
+}
 /**
- * OWM's own defaults for an axis a statement did not give
- * (`extractLocation`, `constants/extractionFunctions.ts`). Used rather than a
- * layout of our own, so an artefact this reader places without coordinates
- * lands where the tool that wrote the file would have drawn it.
+ * An inertia bar, centred where it was drawn. The DSL has no statement for
+ * one — `inertia` is a modifier this reader carries in a line's tail — so only
+ * a picture ever produces it.
  */
-export declare const OWM_DEFAULT_VISIBILITY = 0.9;
-export declare const OWM_DEFAULT_EVOLUTION = 0.1;
+export interface WardleyInertiaStatement {
+    visibility: number;
+    evolution: number;
+}
+export interface WardleyStatements {
+    nodes: WardleyNodeStatement[];
+    pipelines: WardleyPipelineStatement[];
+    notes: WardleyNoteStatement[];
+    evolutions: WardleyEvolveStatement[];
+    links: WardleyLinkStatement[];
+    inertias: WardleyInertiaStatement[];
+}
 /**
  * An OWM document as element props, plus what became of every line.
  *
@@ -144,3 +126,22 @@ export declare const OWM_DEFAULT_EVOLUTION = 0.1;
  * @param context the caller's name for it, used only if the file names nothing.
  */
 export declare function importWardleyOwm(source: string, context?: InterchangeImportContext): InterchangeImportResult;
+/**
+ * Statements as element props, on a new map at the reference size — the OWM
+ * reader's own layout, shared with the SVG reader (ADR 0032 §2.3) so the two
+ * paths draw the same elements.
+ *
+ * Every element that a later statement refers to carries its identity under
+ * `interchange.owm.id` (D3): the OWM reader hands that to the materializer
+ * as is, and the SVG reader turns it into a provisional local id and drops
+ * the payload, because a picture promises no round-trip.
+ *
+ * @param options.mapPayload what rides on the map element under `owm`, if
+ *   anything.
+ * @param options.onInvented told of every position this layout made up.
+ */
+export declare function layoutWardleyStatements(statements: WardleyStatements, options: {
+    mapPayload?: ForeignInterchange;
+    onInvented: (element: string, name: string, why: string, whyKey?: string) => void;
+}): SerializedElementProps[];
+export {};