@formicoidea/labre-framework-wardley 0.42.0 → 0.45.0

package/dist/svg-import.js

@@ -0,0 +1,309 @@
+import { sanitizeSvg, sketchSvgTree, SVG_SKETCH_EMPTY, SvgSketchNotebook, } from '@formicoidea/labre-core/blocks/surface';
+import { FontFamily, TextAlign } from '@formicoidea/labre-core/model';
+import { fillPlaceholders } from '@formicoidea/labre-core/shared/services';
+import { OWM_DEFAULT_MAP_WIDTH, owmCoordsOf, owmDefaultPlot, WARDLEY_OWM_FORMAT_ID, } from './export.js';
+import { layoutWardleyStatements } from './import.js';
+import { NODE_STROKE } from './node/consts.js';
+import { recogniseLabreExport } from './svg-recognise-labre.js';
+import { recogniseOnlineWardleyMaps } from './svg-recognise-owm.js';
+import { recogniseWardleyMapRenderer } from './svg-recognise-renderer.js';
+import { recogniseByShape } from './svg-recognise-shapes.js';
+import { WARDLEY_SVG_IMPORT_REMARKS } from './svg-remarks.js';
+/**
+ * **A Wardley SVG, read as the map it is a picture of** (ADR 0032).
+ *
+ * ## The heuristics statement, and its known failure modes
+ *
+ * _ADR 0012's open question 2, answered for Wardley beside the parser that
+ * makes the guesses. What reaches the shared sketch walk is covered by that
+ * walk's own statement (`blocks/surface/src/extensions/svg-sketch.ts`); this
+ * one covers what is CLAIMED before it._
+ *
+ * **What it guesses, and from what.** Roles, relations and coordinates — and
+ * only when it can say where they came from. A producer is detected by a
+ * structural marker on the sanitised tree, never by searching the text, in a
+ * fixed order that stops at the first certain match: Labre's own board export
+ * (its `data-labre-svg` root and per-element `data-labre-*` markers, which
+ * state roles exactly, `svg-recognise-labre.ts`), then wardley-map-renderer
+ * (its `axes` and `nodes` layers, `svg-recognise-renderer.ts`), then
+ * OnlineWardleyMaps (an element marker inside its own movable wrapper,
+ * `svg-recognise-owm.ts`), then — no marker at all — the shapes themselves
+ * (`svg-recognise-shapes.ts`), which promote components and dependencies and
+ * nothing else, and only once they have found the two axes of a plot; with
+ * no plot, the whole file is a sketch and the report says no axes were found.
+ * A recogniser reads the producer's components,
+ * anchors, markets, ecosystems, climate arrows, pipelines, evolved twins,
+ * inertia bars, notes, dependencies and title, and the PLOT they sit on;
+ * `[visibility, evolution]` is then read off that plot (`owmCoordsOf`) and
+ * laid on a new native board at the reference size with the OWM importer's own
+ * layout (`layoutWardleyStatements`), so a map that arrives as a picture and
+ * one that arrives as `.owm` text are the same elements.
+ *
+ * **Where it is known to be wrong.** A name is what the producer DREW: a
+ * truncated or wrapped label arrives truncated or joined. A producer certain
+ * but plot-less file (its `fillArea` stripped) is laid out over the extent of
+ * its own components, and the report says those coordinates were ESTIMATED
+ * (`invented-layout`). OnlineWardleyMaps draws a climate arrow with no name, so
+ * one arrives unnamed. The renderer's dependencies name no node — their
+ * `data-id` is the relation's own — so their ends are bound by geometry in
+ * both modes, each within its node's reach; its static output carries no id
+ * at all, so a name is the label drawn nearest its node, closest pairs first,
+ * and two nodes crowded closer than their labels can swap names. The renderer
+ * draws no evolved twin, so the twin takes the moving node's name. Methods,
+ * annotations, PST boxes, steps and flow labels have no native
+ * artefact and arrive as a sketch. The title is drawn as a free text above the
+ * board, because a board stores no title of its own. Nothing of the source
+ * tool's MODEL beyond the drawing survives: the OWM DSL stays the reference
+ * Wardley import.
+ *
+ * **Everything else is the sketch's.** What the recogniser did not consume —
+ * a logo, a hand-drawn remark, an artefact it has no sentence for — is read by
+ * the shared walk exactly as before, placed so that the file's plot lands on
+ * the board's plot (a uniform scale, centred), in the SAME result: one import,
+ * one undo step. The report counts it in one `warning`.
+ *
+ * ## Still the visual tier
+ *
+ * No `interchange` payload on any element, `carried` and `quarantined` always
+ * `0`, no round-trip promised (ADR 0012 P2, which ADR 0032 §1 keeps). The OWM
+ * layout attaches `interchange.owm` to the elements a later statement refers
+ * to; here that identity becomes a provisional local `id` the materializer
+ * replaces with a nanoid, and the payload is dropped.
+ *
+ * ## Ids are ids
+ *
+ * A producer's id, forged or not, is only ever a provisional local name and a
+ * `Map` key (`svg-read.ts`); a name is the text the sanitised tree holds; a
+ * coordinate that is not a finite number sends its element to the sketch with
+ * a remark. Nothing is evaluated: the sanitiser has already removed what could
+ * run, and this reads attributes and text content only.
+ *
+ * Pure, like every reader (P3): exported from the package index, so
+ * labre-mcp calls the same function the command does.
+ */
+/** Detection order (ADR 0032 §4): the first certain match wins. */
+const RECOGNISERS = [
+    recogniseLabreExport,
+    recogniseWardleyMapRenderer,
+    recogniseOnlineWardleyMaps,
+    recogniseByShape,
+];
+export function importWardleySvg(source, context = {}) {
+    // What a board is called is the document's business; the map's own title,
+    // when the picture drew one, is drawn back as a text.
+    void context;
+    const notebook = new SvgSketchNotebook();
+    const root = sanitizeSvg(source, notebook);
+    let drawn;
+    for (const recognise of RECOGNISERS) {
+        drawn = recognise(root);
+        if (drawn)
+            break;
+    }
+    if (!drawn)
+        return sketchOnly(root, notebook);
+    return mapAndSketch(root, notebook, drawn);
+}
+/**
+ * Nothing recognised — no producer marked the file and no axes were found —
+ * so today's sketch, word for word, plus the one sentence that says why
+ * (ADR 0032 §5).
+ */
+function sketchOnly(root, notebook) {
+    const elements = sketchSvgTree(root, notebook);
+    if (elements.length === 0) {
+        notebook.once('empty', SVG_SKETCH_EMPTY[1], SVG_SKETCH_EMPTY);
+    }
+    return {
+        elements,
+        report: {
+            mapped: elements.length,
+            carried: 0,
+            quarantined: 0,
+            notes: [
+                {
+                    kind: 'warning',
+                    message: WARDLEY_SVG_IMPORT_REMARKS.noAxes[1],
+                    messageKey: WARDLEY_SVG_IMPORT_REMARKS.noAxes[0],
+                },
+                ...notebook.notes,
+            ],
+        },
+    };
+}
+/** The extent of what was drawn, standing in for a plot the file lost. */
+function extentPlot(drawn) {
+    const xs = [
+        ...drawn.nodes.map(node => node.x),
+        ...drawn.notes.map(note => note.x),
+    ];
+    const ys = [
+        ...drawn.nodes.map(node => node.y),
+        ...drawn.notes.map(note => note.y),
+    ];
+    if (xs.length === 0)
+        return { x0: 0, y0: 0, width: 1, height: 1 };
+    const x0 = Math.min(...xs);
+    const y0 = Math.min(...ys);
+    return {
+        x0,
+        y0,
+        width: Math.max(Math.max(...xs) - x0, 1),
+        height: Math.max(Math.max(...ys) - y0, 1),
+    };
+}
+/**
+ * The frame that lands the file's plot on the board's: one uniform scale (a
+ * sketch has no independent axes), centred — the default
+ * `preserveAspectRatio` of the format itself.
+ */
+function placeOnBoard(file, board) {
+    const s = Math.min(board.width / file.width, board.height / file.height);
+    return {
+        s,
+        ox: board.x0 + board.width / 2 - s * (file.x0 + file.width / 2),
+        oy: board.y0 + board.height / 2 - s * (file.y0 + file.height / 2),
+    };
+}
+function mapAndSketch(root, notebook, drawn) {
+    const notes = [...drawn.remarks];
+    const plot = drawn.plot ?? extentPlot(drawn);
+    if (!drawn.plot) {
+        notes.push({
+            kind: 'invented-layout',
+            element: 'map',
+            message: WARDLEY_SVG_IMPORT_REMARKS.inventedPlot[1],
+            messageKey: WARDLEY_SVG_IMPORT_REMARKS.inventedPlot[0],
+        });
+    }
+    const at = (x, y) => owmCoordsOf(plot, x, y);
+    const byId = new Map(drawn.nodes.map(node => [node.id, node]));
+    const statements = {
+        nodes: drawn.nodes.map(node => ({
+            keyword: node.kind,
+            name: node.name,
+            id: node.id,
+            ...at(node.x, node.y),
+            tail: '',
+            invented: false,
+        })),
+        pipelines: drawn.pipelines.flatMap(pipeline => {
+            if (!('of' in pipeline)) {
+                return [
+                    {
+                        name: pipeline.name,
+                        id: pipeline.id,
+                        from: at(pipeline.x1, pipeline.top).evolution,
+                        to: at(pipeline.x2, pipeline.top).evolution,
+                        top: at(pipeline.x1, pipeline.top).visibility,
+                        tail: '',
+                        invented: false,
+                    },
+                ];
+            }
+            const owner = byId.get(pipeline.of);
+            if (!owner)
+                return [];
+            return [
+                {
+                    name: owner.name,
+                    id: owner.id,
+                    from: at(pipeline.x1, owner.y).evolution,
+                    to: at(pipeline.x2, owner.y).evolution,
+                    tail: '',
+                    invented: false,
+                },
+            ];
+        }),
+        notes: drawn.notes.map(note => ({
+            text: note.text,
+            ...at(note.x, note.y),
+            tail: '',
+            invented: false,
+        })),
+        evolutions: drawn.evolutions.flatMap(evolution => {
+            const owner = byId.get(evolution.of);
+            if (!owner)
+                return [];
+            return [
+                {
+                    name: owner.name,
+                    id: owner.id,
+                    becomes: evolution.name,
+                    evolution: at(evolution.x, owner.y).evolution,
+                    tail: '',
+                    invented: false,
+                },
+            ];
+        }),
+        links: drawn.links,
+        inertias: drawn.inertias.map(inertia => at(inertia.x, inertia.y)),
+    };
+    const native = layoutWardleyStatements(statements, {
+        onInvented: (element, name, why, whyKey) => notes.push({
+            kind: 'invented-layout',
+            sourceId: name,
+            element,
+            message: why,
+            ...(whyKey ? { messageKey: whyKey } : {}),
+        }),
+    }).map(provisional);
+    if (drawn.title)
+        native.push(titleProps(drawn.title));
+    const board = owmDefaultPlot();
+    const sketch = sketchSvgTree(root, notebook, {
+        skip: drawn.consumed,
+        place: placeOnBoard(plot, board),
+    });
+    if (sketch.length > 0) {
+        notes.push({
+            kind: 'warning',
+            message: fillPlaceholders(WARDLEY_SVG_IMPORT_REMARKS.sketchedRemainder[1], {
+                count: sketch.length,
+            }),
+            messageKey: WARDLEY_SVG_IMPORT_REMARKS.sketchedRemainder[0],
+            messageParams: { count: sketch.length },
+        });
+    }
+    const elements = [...native, ...sketch];
+    return {
+        elements,
+        report: {
+            mapped: elements.length,
+            carried: 0,
+            quarantined: 0,
+            notes: [...notes, ...notebook.notes],
+            sourceVersion: drawn.producer,
+        },
+    };
+}
+/**
+ * One laid-out element with its OWM identity turned into a provisional local
+ * id, and the payload gone: the identity wires the connectors
+ * (`materializeInterchangeImport`), and a picture carries nothing to round-trip.
+ */
+function provisional(props) {
+    const carried = props.interchange;
+    if (carried === undefined)
+        return props;
+    const rest = { ...props };
+    delete rest.interchange;
+    const id = carried[WARDLEY_OWM_FORMAT_ID]?.id;
+    return typeof id === 'string' ? { ...rest, id } : rest;
+}
+/**
+ * The map's title, where the shipped maps draw theirs: centred above the plot,
+ * across the board (`templates/maps.ts`). A free text, because a board stores
+ * no title of its own.
+ */
+function titleProps(text) {
+    return {
+        type: 'text',
+        text,
+        color: NODE_STROKE,
+        fontFamily: FontFamily.Inter,
+        fontSize: 28,
+        textAlign: TextAlign.Center,
+        xywh: `[${OWM_DEFAULT_MAP_WIDTH / 2 - 500},12,1000,40]`,
+    };
+}

package/dist/svg-read.d.ts

@@ -0,0 +1,108 @@
+import type { InterchangeNote } from '@formicoidea/labre-core/blocks/surface';
+import type { OwmPlot } from './export.js';
+import type { WardleyNodeKeyword } from './import.js';
+/**
+ * What a recogniser reads off a picture, before anything is laid out — the
+ * shared shape every producer's recogniser answers in (ADR 0032 §2.2).
+ *
+ * Everything is in the FILE's coordinates, exactly as the shared sketch walk
+ * would place it (`svgFrameOf`), so `svg-import.ts` can turn a point into
+ * `[visibility, evolution]` against the plot the recogniser found, and place
+ * the remainder with the same arithmetic.
+ */
+export interface DrawnWardleyNode {
+    /** The producer's own id, used as a provisional local name and nothing else. */
+    id: string;
+    kind: WardleyNodeKeyword;
+    /** What the producer drew beside it, verbatim (truncated stays truncated). */
+    name: string;
+    x: number;
+    y: number;
+}
+export interface DrawnWardleyMap {
+    /** `sourceVersion`: the producer, and the marker version it read. */
+    producer: string;
+    /** The plot, read off the file; absent when the producer is certain but the file lost it. */
+    plot?: OwmPlot;
+    title?: string;
+    nodes: DrawnWardleyNode[];
+    /**
+     * A pipeline body: either hung under a component (`of`, OnlineWardleyMaps'
+     * reading), or standing alone with its own id, name and top edge (`top`,
+     * the renderer's).
+     */
+    pipelines: ({
+        of: string;
+        x1: number;
+        x2: number;
+    } | {
+        id: string;
+        name: string;
+        top: number;
+        x1: number;
+        x2: number;
+    })[];
+    /** An evolved twin: which node moves, what the twin is called, where it lands. */
+    evolutions: {
+        of: string;
+        name: string;
+        x: number;
+    }[];
+    /** Consumer, then what it needs (ADR 0010), by producer id. */
+    links: {
+        from: string;
+        to: string;
+    }[];
+    notes: {
+        text: string;
+        x: number;
+        y: number;
+    }[];
+    inertias: {
+        x: number;
+        y: number;
+    }[];
+    /** Every node the recogniser turned into the above; the sketch skips them. */
+    consumed: Set<Element>;
+    /** What the recogniser has to say about the file (dangling ends, bad numbers). */
+    remarks: InterchangeNote[];
+}
+/**
+ * A recogniser's answer before it has read anything, and the one way it marks
+ * an element as turned into a native one (so the sketch skips it).
+ *
+ * `head` is spread first, so the result's keys keep the order every
+ * recogniser wrote them in — a `plot` passed here, even `undefined`, sits
+ * after `producer`; one found later is assigned at the end.
+ */
+export declare function startDrawnMap(head: Pick<DrawnWardleyMap, 'producer'> & Partial<Pick<DrawnWardleyMap, 'plot'>>): {
+    drawn: DrawnWardleyMap;
+    consume: (element: Element | undefined) => void;
+};
+/**
+ * Every element carrying an `id`, first wins — the index a producer's markers
+ * are looked up in.
+ *
+ * A `Map`, never an object: a hostile file's `__proto__` or `constructor` is a
+ * key like any other here, and can never reach a prototype (ADR 0032 §7).
+ */
+export declare function idIndex(root: Element): Map<string, Element>;
+/**
+ * A text's words, collapsed the way the sketch collapses a label — one span
+ * per line joined by a space, so a name a producer wrapped over two `<tspan>`s
+ * reads as the name and not as two words glued together.
+ */
+export declare function textOf(element: Element | undefined): string;
+/**
+ * Where an element's own user-space origin lands, or `undefined` when the
+ * file does not give it as numbers.
+ *
+ * The shared frame reader is lenient — it reads the numbers out of a
+ * transform and skips what is not one — which is right for a sketch and wrong
+ * for a coordinate this import is about to present as READ. So an element
+ * whose own `transform` is anything but a translate of finite numbers is
+ * refused here, and the caller sends it to the sketch with a remark.
+ */
+export declare function originOf(element: Element): [number, number] | undefined;
+/** A finite number off an attribute, or `undefined`. */
+export declare function finiteAttr(element: Element, name: string): number | undefined;

package/dist/svg-read.js

@@ -0,0 +1,89 @@
+import { svgFrameOf } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * A recogniser's answer before it has read anything, and the one way it marks
+ * an element as turned into a native one (so the sketch skips it).
+ *
+ * `head` is spread first, so the result's keys keep the order every
+ * recogniser wrote them in — a `plot` passed here, even `undefined`, sits
+ * after `producer`; one found later is assigned at the end.
+ */
+export function startDrawnMap(head) {
+    const drawn = {
+        ...head,
+        nodes: [],
+        pipelines: [],
+        evolutions: [],
+        links: [],
+        notes: [],
+        inertias: [],
+        consumed: new Set(),
+        remarks: [],
+    };
+    const consume = (element) => {
+        if (element)
+            drawn.consumed.add(element);
+    };
+    return { drawn, consume };
+}
+/**
+ * Every element carrying an `id`, first wins — the index a producer's markers
+ * are looked up in.
+ *
+ * A `Map`, never an object: a hostile file's `__proto__` or `constructor` is a
+ * key like any other here, and can never reach a prototype (ADR 0032 §7).
+ */
+export function idIndex(root) {
+    const index = new Map();
+    for (const element of Array.from(root.querySelectorAll('[id]'))) {
+        const id = element.getAttribute('id');
+        if (id !== null && !index.has(id))
+            index.set(id, element);
+    }
+    return index;
+}
+/**
+ * A text's words, collapsed the way the sketch collapses a label — one span
+ * per line joined by a space, so a name a producer wrapped over two `<tspan>`s
+ * reads as the name and not as two words glued together.
+ */
+export function textOf(element) {
+    if (!element)
+        return '';
+    const spans = Array.from(element.children).filter(child => child.localName === 'tspan');
+    const raw = spans.length > 0
+        ? spans.map(span => span.textContent ?? '').join(' ')
+        : (element.textContent ?? '');
+    return raw.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Where an element's own user-space origin lands, or `undefined` when the
+ * file does not give it as numbers.
+ *
+ * The shared frame reader is lenient — it reads the numbers out of a
+ * transform and skips what is not one — which is right for a sketch and wrong
+ * for a coordinate this import is about to present as READ. So an element
+ * whose own `transform` is anything but a translate of finite numbers is
+ * refused here, and the caller sends it to the sketch with a remark.
+ */
+export function originOf(element) {
+    const raw = element.getAttribute('transform');
+    if (raw !== null && raw.trim().length > 0) {
+        const match = /^\s*translate\(\s*([^,\s)]+)(?:[\s,]+([^,\s)]+))?\s*\)\s*$/.exec(raw);
+        if (!match)
+            return undefined;
+        for (const value of [match[1], match[2] ?? '0']) {
+            if (!Number.isFinite(Number(value)))
+                return undefined;
+        }
+    }
+    const frame = svgFrameOf(element);
+    return [frame.ox, frame.oy];
+}
+/** A finite number off an attribute, or `undefined`. */
+export function finiteAttr(element, name) {
+    const raw = element.getAttribute(name);
+    if (raw === null || raw.trim().length === 0)
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}

package/dist/svg-recognise-labre.d.ts

@@ -0,0 +1,2 @@
+import { type DrawnWardleyMap } from './svg-read.js';
+export declare function recogniseLabreExport(root: Element): DrawnWardleyMap | undefined;